Metadata-Version: 2.4
Name: stml-cli
Version: 0.1.0
Summary: The stml partner CLI — pull, edit, push, and publish stml apps and libraries.
Author: stml
Project-URL: Homepage, https://stml.io
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: certifi

# stml — the partner CLI

Pull an app you built on the platform down to a local folder, edit it with your
own editor and git, push it back to test, and publish a finished version to the
App Store — without cloning the stml4 monorepo.

Spec: [`docs/user-stories/feature/024-app-authoring-platform.md`](../docs/user-stories/feature/024-app-authoring-platform.md).

## Requirements

- **Python 3.11 or newer** on your PATH. That's the only hard requirement.
  - macOS: `brew install python@3.12` (or python.org). **Not** the system
    `/usr/bin/python3` — it's often 3.9, which is too old.
  - Linux: your distro's Python 3.11+, or `pipx`/`pyenv`/`uv`.
  - Windows 10/11: the python.org installer (gives you the `py` launcher).

## Install

| Method | Command |
|---|---|
| **pipx** (recommended) | `pipx install stml-cli` |
| pip (in a venv) | `pip install stml-cli` |
| single file (no installer) | `curl -fsSL <backend>/cli/stml -o stml && chmod +x stml` |

Runs on **macOS, Linux, and Windows** — it's pure-Python and touches nothing
platform-specific beyond the filesystem and HTTPS.

## Quickstart

```sh
# Point at your backend (default: http://localhost:8010)
export STML4_BACKEND=https://api.stml.io

# 1. Sign in — opens your browser; approve, and a session is cached locally.
stml login
stml whoami

# 2. See your apps and their URLs (the handle you pull/push by).
stml list

# 3. Pull an app's source into a folder — identify it by its URL (copy from
#    `stml list` or the browser; a trailing /flows/… or /sessions/… is fine).
stml pull https://app.stml.io/orgs/acme/ws/main/apps/my-app-a1b2 ./my-app

# 3. Edit with your own tools, commit to git, whatever.

# 4. Push it back — checks, writes the overlay, and deploys in one step.
stml push ./my-app          # app remembered from pull
#   or: stml push https://app.stml.io/orgs/acme/ws/main/apps/my-app-a1b2 ./my-app

# 5. When ready, publish a version to the App Store.
#    (bump project.version in pyproject.toml first; set [tool.stml].issuer-org)
stml publish ./my-app
```

## Authentication

`stml login` runs the platform's browser OAuth flow (the same one the monorepo's
`npm run libs:login` uses): you authenticate in the browser, approve, and a
**refresh token** is cached under your OS config dir (`~/Library/Application
Support/stml`, `$XDG_CONFIG_HOME/stml`, or `%APPDATA%\stml`). Access tokens are
minted per-command and never written to disk.

`STML4_TOKEN`, if set, overrides the cache verbatim — how CI and the monorepo
(`STML4_TOKEN=$(npm run --silent token)`) authenticate.

## Commands

| Command | What |
|---|---|
| `stml login` / `logout` / `whoami` | session auth |
| `stml list [--workspace <ws>]` | list your apps with their app URLs |
| `stml pull <app-url> [<dir>]` | pull overlay source to a folder (bare slug also works) |
| `stml push [<app-url>] <dir>` | push a folder to the overlay **and deploy** (`--no-deploy`, `--prune`) |
| `stml publish <dir> [--org <slug>]` | publish a library version from a folder |
| `stml init <dir> [--name <name>]` | scaffold a new library directory |
