Last updated 2026-05-07

Command Reference

Every stax command, every flag. Sourced from the Cobra definitions in platform/cli-go/internal/commands/. Run any command with --help for an interactive view.

Global flags

Flag	Default	Description
`--version`		Print the binary version (set at build time via ldflags).
`--help`		Print Cobra-rendered help for the current command.
`--dry-run`	`false`	Preview supported side effects without mutating local or remote state.

Stacked-diff workflow

`stax clone <repo>`

Clone a GitHub repository and create the .stax/ workspace inside.

Accepts owner/repo, full HTTPS, or SSH URL.
Adds .stax/ to .git/info/exclude so it is never committed.

`stax feature|fix|docs|chore|start <name>`

Start a new branch and feature record. Branch and commit prefixes match the verb (see Workflow → Starting work).

`stax diff [message]`

Save a diff in the current feature.

Flag	Description
`--preview`	Show what would be staged without committing.
`--update`	Amend the diff currently being edited.

`stax diff edit <label>`

Enter edit mode for diff D1, D2, etc. Subsequent stax diff --update calls amend that diff.

`stax diff check [label]`

Run the runner against the diff's commit. With no label, runs against the latest diff.

`stax sync`

Rebase the current feature on origin/main.

Flag	Description
`--continue`	Continue after manually resolving conflicts.
`--abort`	Abort an in-progress sync and return to the prior state.

`stax switch <query>`

Fuzzy-match against feature names and switch. Auto-saves uncommitted work first.

`stax submit`

Push the feature branch and open or update its pull request via the gh CLI.

Flag	Description
`--preview`	Print what would be pushed without doing it.

`stax land [label]`

Squash-merge an approved diff into origin/main. Default target is the lowest-position approved diff.

Flag	Description
`--force`	Skip approval and CI checks.

`stax features`

List all features in the current repo with diff counts and a marker for the current one.

`stax diffs`

List diffs for the current feature in stack order.

`stax context`

Print a single-line summary: feature name, current diff, branch, dirty state.

`stax status`

Like git status but with diff metadata layered on top.

`stax log`

Print the activity log.

Flag	Default	Description
`-n, --limit`	`20`	Number of entries to show.

`stax undo`

Undo the last state-changing command using the activity log.

Flag	Description
`--list`	Show what is currently undoable.

`stax split`

Split the current uncommitted changes into multiple diffs by walking through hunks.

Flag	Description
`--preview`	Show the proposed split without applying it.

`stax config`

Read or update workspace configuration in .stax/config.json.

stax config              # print all values
stax config get <key>    # print one value
stax config set <key> <value>

Local runner

`stax runner start`

Spawn the runner as a detached background process. Writes a PID file at ~/.local/share/stax/runner.pid.

Flag	Default	Description
`-w, --workspace`	cwd	Path the runner serves from.
`-p, --port`	`4800`	HTTP port.

`stax runner stop`

Send SIGTERM to the running runner using the PID file.

`stax runner status`

Check whether the runner is reachable on its port.

`stax workflows`

List workflows under .github/workflows/ with their triggers, jobs, and inputs.

`stax run <workflow>`

Trigger a workflow run and stream its output.

Flag	Description
`-i, --input KEY=VALUE`	Pass a workflow_dispatch input. Repeatable.
`--no-sandbox`	Run in-place rather than in a sandboxed copy.
`--no-wait`	Print the run ID and return immediately.

`stax runs`

List recent runs.

Flag	Default	Description
`-s, --status`		Filter by `queued\|in_progress\|completed\|failed\|cancelled`.
`-l, --limit`	`10`	Number of runs to show.

`stax runs view <id>`

Print run metadata: jobs, steps, conclusions, durations.

`stax runs logs <id>`

Print full concatenated logs (text/plain) for a run.

`stax log <run-id>` / `stax log -f`

Stream the live log of a run via the runner's SSE endpoint.

`stax secret` — runner mirror store

stax secret list
stax secret set <name> [value]      # value can come from arg, stdin, or hidden prompt
stax secret delete <name>
stax secret import <file>           # .env-formatted file
stax secret sync                    # pull from cloud backends
stax secret status                  # which backends are active

`stax secrets` — repo-backed SOPS + age

Manages encrypted files committed to git. The sops binary is required for decrypt/edit/export operations; Stax manages scaffolding, age identities, recipient metadata, verification, and runner sync.

stax secrets init
stax secrets keygen
stax secrets pubkey
stax secrets verify
stax secrets edit --env production
stax secrets get <KEY> --env production
stax secrets list --env production
stax secrets export --env production --format shell
stax secrets add-recipient <age1...> --name "Name <email>" --role engineer
stax secrets remove-recipient <age1...>
stax secrets recipients
stax secrets sync runner
stax secrets status

Command	Important flags
`init`	`--env`, `--file`, `--format yaml\|json\|dotenv`, `--recipient`, `--direnv`, `--install-hook`, `--force`
`edit`	`--env` when multiple managed files exist.
`get` / `list`	`--env` merges default + target environment when set.
`export`	`--env`, `--format shell\|dotenv`.
`add-recipient`	`--name` required, `--role` defaults to `engineer`.
`sync`	Only `runner` is implemented today.

`stax vault`

Links a repository to shared secret backends. SOPS + age is the preferred repo-backed path; 1Password and Doppler remain available for teams that already use an external vault.

stax vault login [--backend 1password|doppler|sops-age]
stax vault link [--backend 1password] <vault-name>
stax vault link --backend doppler <project> <config>
stax vault link --backend sops-age --env production infra/secrets/prod.enc.yaml
stax vault status
stax vault sync
stax vault list

stax vault age generate
stax vault age import [file]
stax vault age public
stax vault age remove
stax vault edit <file>
stax vault decrypt <file>

`stax dashboard`

Launch the Next.js dashboard and open it in the default browser.

Flag	Default	Description
`-p, --port`	`3000`	Port for the dashboard.

Affected test runner

`stax test`

Run tests for projects affected by the current change set, with content-addressable caching. See the dedicated page for the full model.

Flag	Description
`--all`	Test every project regardless of changes.
`--project <name>`	Test a single named project.
`--no-cache`	Skip cache lookup; run all tests.
`--update-cache`	Force a re-run and update cache entries.
`--cache-stats`	Print cache hit / miss / size statistics.
`--cache-clear`	Clear the cache (optionally for a single project).
`--retry-failed`	Force re-run of cached failures.
`--base <ref>`	Base branch / ref for change detection (default: `main`).

Command Reference

Global flags

Stacked-diff workflow

stax clone <repo>

stax feature|fix|docs|chore|start <name>

stax diff [message]

stax diff edit <label>

stax diff check [label]

stax sync

stax switch <query>

stax submit

stax land [label]

stax features

stax diffs

stax context

stax status

stax log

stax undo

stax split

stax config