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.

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

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

Quickstart

# Talks to https://api.stml.io by default — nothing to set.
# Override only for local dev:  export STML4_BACKEND=http://localhost:8010

# 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: 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

Authoring & collaboration walkthrough (modes, forking, team workflow): docs/guides/authoring-apps.md.