Last updated 2026-05-07

CLI Overview

The stax CLI is a single Go binary that wraps the stacked-diff workflow, controls the local runner, and launches the dashboard. There is also a legacy TypeScript implementation under platform/cli/; the documentation here always refers to the Go binary unless explicitly stated.

Two halves

Conceptually the CLI does two distinct jobs that you can use independently:

1. Stacked-diff workflow

Hides git behind a verb-driven workflow. You don't git rebase or git push directly — you stax sync and stax submit. 

stax clone myorg/repo
stax feature "user auth"
stax diff "Add login form"
stax sync
stax submit
stax land

2. Local runner control

HTTP wrappers around the runner's REST API. Trigger workflows, inspect runs, manage local runner secrets, manage repo-backed SOPS secrets, launch the dashboard. 

stax runner start
stax workflows
stax run ci -i environment=staging
stax runs
stax log <run-id> -f
stax secret set NPM_TOKEN
stax secrets verify
stax dashboard

Where state lives

LocationWhat's there
.stax/ in each cloned repo features.json, diff metadata, activity log. Excluded via .git/info/exclude.
~/.local/share/stax/runner.pid Runner PID file (used by runner stop / status).
~/.local/share/local-runner/secrets/ Per-workspace runner mirror, keyed by SHA-256 of the workspace path.
infra/secrets/*.enc.yaml + .sops.yaml Committed SOPS + age encrypted secret files and recipient policy.
~/.config/sops/age/keys.txt or macOS Keychain Local age private identity used to decrypt repo-backed secrets. Never committed.
~/.local/share/local-runner/actions-cache/ Cached marketplace actions (24h TTL by default).
~/.local/share/local-runner/cache/ Filesystem-backed actions/cache data.
/tmp/runner-sandboxes/ Per-run sandbox workspaces. Cleaned automatically.

Conventions

  • All commands accept --help for full Cobra-rendered usage. The CLI also prints a relevant "next step" hint at the bottom of most successful runs.
  • Mutating commands support the global --dry-run flag where a meaningful preview exists.
  • The CLI calls the runner over http://localhost:4800. Override with RUNNER_URL if you've moved the port (or pass --port on relevant commands).
  • The CLI auto-saves uncommitted changes (as a WIP: auto-save commit) before switching context — you'll never lose work to a wrong switch.

Continue reading