Full command reference¶

The complete command surface. For day-to-day commands only, see Core commands. For navigation specifically, see Navigation.

Global diagnostics¶

Add --trace before or after any subcommand to print instrumented Git subprocess timings, the summed Git time, and command wall time. URL- and token-shaped arguments are redacted.

st --trace status --json >/dev/null

Stack operations¶

st merge variants¶

• st merge — local cascade merge with provenance-aware descendant rebases, then st rs --force unless --no-sync
• st merge --when-ready — wait for CI + approvals + mergeability; incompatible with --dry-run, --no-wait, --remote, and --queue
• st merge --downstack-only / --ds — merge ancestors below the current branch, then rebase the current branch onto trunk; composes with --stack, and is incompatible with --all, --full, --remote, and --queue
• st merge --stack — GitHub/GitLab stack merge: target every selected PR/MR to trunk, merge only the selected tip with SHA-preserving merge, and poll lower items for authoritative merged state; timed-out items stay open. Multi-PR GitHub rebase/squash fails before mutation because rewritten SHAs prevent genuine lower-PR merged state; a single selected GitHub PR may still use them. GitLab first verifies project merge settings, sends squash: false, and rejects explicit rebase/squash. Gitea/Forgejo is unsupported
• st merge --stack --full — include descendants above the current branch and land the full stack through the actual stack tip
• st merge --remote — merge entirely via GitHub API, no local git operations (GitHub only)
• st merge --queue — enqueue PRs into GitHub merge queue / GitLab merge trains, polling only within the configured timeout deadline

See also: Merge and cascade

Navigation¶

Branch management¶

st branch track --all is local and metadata-only: it does not contact a forge, fetch or change remotes/upstreams, load remote configuration, or switch branches. It snapshots the untracked non-trunk local branches before writing metadata and leaves existing tracked metadata and the trunk untouched. For each target, it chooses the cycle-safe strict local ancestor with the fewest commits between that ancestor and the target, breaking equal-distance ties lexically by branch name. Non-trunk branches at the same commit are never selected as one another's parent. When no cycle-safe strict local ancestor exists, including for unrelated histories, the branch is parented to trunk; trunk remains the fallback root even when it points at the same commit. --all conflicts with --parent and --all-prs.

Up/down scopes¶

Interactive modes¶

Recovery¶

Health and testing¶

CI, PRs, and reporting¶

Utilities¶

st skills update fetches the remote body and compares each fully rendered harness file byte-for-byte, rewriting instructions that differ even when the installed package-version marker matches. It leaves byte-identical files untouched; --dry-run reports the same decision without writing. st skills list is intentionally local-only: its current/stale indicator compares the installed package-version marker with this stax binary and does not verify fetched content. When a symlink at the skill directory or file position no longer resolves, st skills update removes it and replaces it with a real path (working symlinks are left intact and written through); if a harness cannot be written for any other reason it is reported and skipped so the remaining harnesses still update, and the command exits non-zero afterwards.

st tmux¶

Worktrees¶

Full guide: Worktrees · AI lanes

st setup¶

Lane launch examples¶

st lane
st lane review-pass "address PR comments"
st lane fix-flaky --agent claude --yolo "stabilize the flaky tests"
st lane big-refactor --agent claude --agent-arg=--verbose "split the auth module"
st wt go ui-polish --run "cursor ." --tmux

Flags by command¶

st modify¶

• -a stage all and amend
• -am "msg" stage all and amend with a new message
• -r restack after amending
• -ar stage all, amend, restack
• With nothing staged in a TTY: menu to stage all, --patch, amend message only, or abort

st create¶

• st add <name> is an alias for st create <name>
• -m "msg" set commit message (with nothing staged in a TTY: menu for stage all, --patch, empty branch, or abort)
• -am "msg" stage all and commit
• --ai generate missing branch name and/or first commit message from local changes
• --ai -a --yes stage all changes, generate branch name + commit message, and skip AI value review prompts
• st create <name> --ai -a keeps <name> and generates the first commit message
• st create --ai -m "msg" keeps the commit message and generates the branch name
• -n, --no-verify skip pre-commit and commit-msg hooks when creating a commit
• -m / -am create the commit before creating the destination branch, including with --from and --below, so hook failures or interrupts do not leave orphan branches
• -m / --ai derived branch names refuse collisions instead of creating -2 duplicates; pass an explicit different name or checkout/reparent the existing branch
• --insert reparent children of the current branch onto the new branch
• --below create from the current branch's parent and reparent the current branch onto the new branch; prepared tracked and untracked changes are auto-stashed and reapplied onto the new lower branch, and -m/-am commits staged changes there
• st branch create --message "msg" --prefix feature/

Prepared-work --below example:

# On an upstack branch, after editing a CVE hotfix that belongs lower down:
st create cve-hotfix --below

# Or commit it immediately on the inserted lower branch:
st create --below -am "fix: patch CVE-2026-0001"

If the stash cannot apply cleanly while committing below, Stax restores the original branch and prepared changes so the same command can be retried after resolving the conflict. For name-only --below, the inserted branch is left in place and the auto-stash remains available for a manual git stash apply.

st status / st ll / st log¶

• --stack <branch> · --current · --compact · --json · --quiet

st submit¶

• --dry-run / --plan prints a read-only plan without fetching, pushing, editing metadata, or calling forge mutation APIs; add --json for the versioned machine-readable schema (currently version 2; action strings are extensible)
• Plans query live remote head IDs with git ls-remote without updating local tracking refs; --no-fetch deliberately plans from cached tracking refs instead
• A stale branch, and each submitted descendant that must follow its temporary publish head, reports evaluate_after_temporary_restack because the final push decision depends on the rewritten commit ID
• Stack-link plans report update_unless_native_link_succeeds when native-stack success would suppress Stax-managed links
• Stack-link and native-stack plans report evaluate_after_pr_discovery when PRs missing from local metadata could change link or fork eligibility at runtime
• Native-stack plans otherwise report skip for known exclusions or attempt when the prerequisites are known
• --draft / --publish / --no-pr / --no-fetch / --no-verify / --open / --quiet / --verbose
• --no-verify (-n) skips pre-push hooks while pushing branches
• --reviewers alice,bob --labels bug,urgent --assignees alice
• --squash squash commits on each branch before pushing
• --ai generate PR title and body with AI; narrow with --title or --body
• --template <name> / --no-template / --edit
• --rerequest-review / --update-title
• --native-stack force-attempt native GitHub Stack registration for this submit; --no-native-stack skips it
• --fork if the upstream push is denied for lack of write access, fall back to submitting the branch from a fork (single branch, GitHub only)
• --yes / --no-prompt

Config: [submit] stack_links = "comment" | "body" | "both" | "off" and native_stack = "auto" | "off" | "link"; [remote] auto_fork and [remote] fork_remote control the fork fallback — see Configuration → Fork fallback for submit.

st completions¶

Generate a completion script without requiring an initialized repository:

st completions bash
st completions zsh
st completions fish
st completions powershell
st completions elvish

st merge¶

• --dry-run / --yes
• --all / --downstack-only (--ds) / --stack / --stack --full / --method squash|merge|rebase
• --when-ready · --when-ready --interval 10
• --remote · --remote --all · --remote --timeout 60 --interval 10
• --queue · --queue --all --yes
• --timeout <minutes> — positive whole minutes (default: 30); zero is rejected
• --interval <seconds> — positive whole seconds (default: 15) for --when-ready, --remote, --queue, and --stack --when-ready; zero is rejected
• --no-wait / --no-sync / --no-delete / --quiet
• --ignore-failed-ci — merge even when CI checks have failed; still blocks on draft, changes-requested, conflicts, and closed. Incompatible with --queue. Use when only optional checks failed and branch protection does not require them.

For --queue, the timeout is a real deadline: stax caps the final sleep to the remaining budget and does not start another forge status poll once the deadline is reached.

st sync / st rs¶

• --restack · --restack --auto-stash-pop
• --delete-upstream-gone
• --force / --safe / --continue / --quiet / --verbose
• --stash / --no-stash — dirty-tree handling before sync starts: --stash auto-stashes without prompting (works with --quiet/--json; does NOT auto-confirm branch deletions); --no-stash fails on a dirty tree and overrides --force; the two conflict at parse time; the dirty-tree error message names --stash. In dry-run mode both flags are accepted but ignored (stderr warning emitted).
• Interactive Sync plan — applies to st sync / st rs only (not st refresh, which skips this prompt). After fetch, stax refreshes PR metadata, then prints one Sync plan (trunk moves, merged/upstream-gone branches with PR numbers when known, optional --restack preview) and asks how to proceed. When deletions are listed: continue and delete all (non-blocking), per-branch prompts, or cancel (Aborted., no undo receipt). When only trunk/restack changes are pending: Proceed with restack / Cancel, or Continue sync / Cancel sync when no restack is requested. Skipped when --quiet, --json, --force, or when there is nothing to confirm.
• --prune — deprecated; accepted for compatibility and emits a stderr warning; use --full to fetch --prune all remote-tracking refs
• --full — classic git fetch --prune <remote> for all remote-tracking refs; unlike the default trunk-only fetch it does not pass --no-tags, so tags reachable from fetched refs are downloaded too. Slower on large repos.
• --dry-run (alias --plan) — read-only preview: probes the remote with ls-remote (no fetch, no FETCH_HEAD write), patches PR states in-memory, classifies the trunk transition, reports merged/upstream-gone candidates and per-branch disposition, previews the restack scope with conflict predictions; always exits 0. --force, --auto-stash-pop, --full, --stash, --no-stash, and --verbose are accepted but ignored (stderr warning emitted for each). --continue conflicts and is rejected by clap.
• --json — emit the sync result as a single JSON document on stdout (schema version 1). Implies non-interactive (quiet=true); does not imply --force (branches that need confirmation are recorded in skipped_branches and left intact). Conflicts with --continue (rejected by clap). Failures still emit the JSON envelope with success: false and exit non-zero. --verbose is ignored (stderr warning emitted). --dry-run --json emits kind: "sync_plan" with dry_run: true and always exits 0.
• JSON schema (kind: "sync", schema_version: 1; action/kind strings are extensible — consumers should treat unknown values as forwards-compatible additions):

• On early-bail paths (e.g. dirty working tree in non-interactive mode) and on restack-conflict paths where finalize never runs, trunk.action is "unknown" — this is intentional.
• Sync is transactional and undoable via st undo. A single receipt covers trunk fast-forwards, deleted branch heads, deleted metadata refs, reparented children's metadata, and the optional restack phase. A no-op sync (nothing changed) writes no receipt so the previous undoable operation remains on the undo stack.
• Imported branches from st get are remote-delete exempt: once they are detected as merged or upstream-gone, sync may delete the local support branch and metadata, but it will not push-delete the imported remote branch.
• The completion footer summarizes the trunk commit, file, and line delta together with non-zero merged-cleanup, imported-update, and restack counts. It reuses sync's existing results and does not perform extra network or Git work.
• When sync itself leaves exceptional work behind, it reports skipped cleanup with its reason, trunk update failures, and cleanup-driven checkout changes. It prints one prioritized next command: a diverged trunk gets non-destructive guidance to inspect and reconcile it with its remote; other trunk failures suggest st trunk; blocked cleanup suggests st sweep. Routine restack health remains visible in st ls and the TUI instead of appearing after every sync.
• When --restack is requested, sync fails closed if its fetch did not succeed or the local trunk did not reach the fetched remote-trunk commit. It restores any sync auto-stash and exits non-zero before imported-branch refresh, merged-branch cleanup, or restacking can rewrite feature refs. st refresh inherits this guard and exits before its submit phase, so it does not push or update PRs after either failure.
• Deletion output lines for locally deleted branches (merged or upstream-gone) append the branch's tip SHA (first 7 characters, dimmed) so you can reference the exact commit that was removed.
• If sync auto-stashed your working tree and then fails on an error path that cannot restore the stash, it prints a warning to stderr naming the stash "stax auto-stash" with instructions to run git stash pop to restore your changes.

st restack¶

• --all / --continue / --quiet
• --stop-here
• --submit-after ask|yes|no

Temporary publish restack¶

st submit, st downstack submit, st branch submit, and st upstack submit can publish a temporary rebased head without moving local branch tips. When a submitted branch needs restack, Stax creates an internal temporary ref, replays the branch's current commits onto the submitted parent for the push, and keeps local metadata unchanged. Descendants chain onto those temporary publish heads so the remote stack stays linear.

If the excluded parent has local-only commits, scoped submit still refuses and asks you to include ancestors with st downstack submit / st submit or restack first. --squash also requires a local restack first because squashing rewrites local branch history.

st resolve¶

• --agent codex --model gpt-5.3-codex --max-rounds 5

st cascade¶

Restack the stack and submit updates, without fetching trunk (offline-friendly).

• --no-pr / --no-submit / --auto-stash-pop

st checkout¶

• --trunk / --parent / --child 1

st web¶

• st web discovers the enclosing Git worktree from the current directory, starts its localhost HTMX workspace, and opens it in the browser.
• st web <path> accepts a repository or any path inside one and opens the enclosing worktree.
• st web --port <n> binds on a specific port (default 8787). --port 0 picks an ephemeral port. If the requested port is busy, stax warns and uses a free OS-selected port.
• st web --no-open starts the server and prints the URL without opening the browser.
• Binds 127.0.0.1 only; no --host flag is available.
• Each session URL embeds an unguessable 48-hex session token: /s/<token>/. Requests with a wrong or missing token return 404.
• Every mutating POST requires a matching CSRF token field; mismatches return 403.
• Host must be local. Requests without Origin are allowed, but a present Origin must exactly equal http://127.0.0.1:<actual-bound-port> (including an ephemeral or busy-port fallback port); cross-site, malformed, duplicate, and wrong-port values return 403. This check is independent of the session token and CSRF protections.
• Only one mutation runs at a time; mutating controls are disabled while an operation is in flight.
• All git operations run in spawn_blocking to avoid blocking the async Tokio runtime.
• Session state is in-memory; restarting the server generates a new token and URL.

• See Web workspace guide for the full routes reference, keyboard shortcuts, and layout details.

• With no argument, st get syncs and restacks the current stack, equivalent to the Graphite gt get current-stack flow.

• The argument may be a remote branch name, origin/<branch>, or a PR number when forge auth is configured.
• --parent <branch> records a non-trunk parent in stax metadata
• --no-checkout fetches and tracks without switching branches
• --downstack skips local upstack branches when the target already exists locally.
• --remote-upstack includes remote-only upstack PR branches discovered from open PR base/head metadata. This is best-effort without Graphite's central backend.
• --no-restack skips the default restack after checkout.
• --unfrozen unfreezes the requested branch before syncing it; frozen targets are otherwise skipped.
• Existing local branches fast-forward when possible, or rebase local-only commits onto the fetched remote tip when branch histories diverge.
• --force resets an existing local branch to the remote tip instead of preserving local commits.
• Branches checked out in another linked worktree are skipped instead of being moved from the current worktree.
• New remote-only branches imported by st get are read-only support branches: submit uses them as stack bases but does not push them or update their PRs. Existing Stax-managed branches keep their ownership metadata when synced with st get.
• st sync --restack refreshes imported branches from their remote tips before restacking descendants; if an imported branch is checked out in a dirty worktree, sync skips it unless --force is used.

st run¶

• --parallel uses detached temporary worktrees, so the main worktree never changes branch.
• --jobs <N> sets the positive concurrency cap (default 8) and requires --parallel.
• Each parallel command receives STAX_RUN_BRANCH with the original logical branch name; Git itself remains on a detached HEAD inside the temporary worktree.
• Output is captured concurrently and printed in deterministic branch order.
• Clean temporary worktrees are removed after success or failure. If a command leaves uncommitted tracked or untracked changes, that worktree is preserved and its recovery path is printed; the branch is counted as failed. Ignored artifacts do not prevent cleanup.
• --parallel conflicts with --fail-fast, because commands may already be running concurrently.

st ci¶

• --stack / --all / --oneline (-1) / --verbose / --watch / --watch --strict / --interval 30 / --json
• For tracked PRs, CI is fetched for the forge's live PR head, so commits added remotely by formatters or other automation are reflected without moving the local branch. If the live PR revision cannot be resolved, stax falls back to the local branch revision.
• CI status is always fetched live. --refresh remains accepted for compatibility but does not change the fetch behavior.
• On GitHub, all commit-status and check-run pages are collected before the latest result for each check is selected and the overall state is calculated.
• Three render modes: the full per-check table (single branch, default), grouped summary cards (--verbose/-v), and the one-line roll-up (--oneline/-1). Any multi-branch view (--stack/--all) defaults to the roll-up; --verbose overrides it back to cards. --oneline and --verbose cannot be combined.
• The roll-up renders one line per branch, base→tip: CI status icon · branch · #PR · draft/ready · PR title · trailing check-count and timing. A bare --oneline defaults its scope to the current stack.
• By default, --watch waits until every check is terminal, even if one check has already failed. Add --strict to exit as soon as any check fails.
• --watch --alert plays built-in success/error sounds; --watch --alert <file> uses one custom sound for either outcome; --watch --no-alert suppresses [ci] alert = true for one run.
• Config can enable alerts by default with [ci] alert = true; set success_alert_sound and/or error_alert_sound to override the per-outcome built-in sounds.

st standup¶

• --all / --hours 48 / --json / --ci
• --ai · --ai --agent claude · --ai --hours 48
• --ai --style slack
• --ai --plain-text / --ai --json / --ai --jit
• --ci checks only the selected branches and may add network latency; combine it with --all to check all tracked branches.
• GitHub authored reviews come from one time-bounded, maximum-100 GraphQL query. GitLab and Gitea mark that signal unsupported rather than scanning every MR/PR.
• JSON preserves reviews_given and needs_attention.ci_failing; use signals.<name>.status (available, unsupported, unavailable, or not_requested) to interpret empty arrays.

st stats¶

• --current scopes to the current stack (ancestors + current + descendants); when the current branch is untracked, the scope is empty and the command still exits 0.
• --json emits a single RepoStats document with top-level keys: scope ("all" or "current"), trunk, current, repo (project slug, omitted with no forge remote), trunk_ahead / trunk_behind (omitted with no remote-tracking branch), stack_shape, pr_mix, health, worktrees, ci (omitted unless --ci produced counts), ci_unavailable_reason (present when --ci was requested but unavailable), attention, biggest_stacks, hygiene, next_actions.
• stack_shape: tracked, independent, deepest, avg_height.
• pr_mix: open (includes drafts), draft, ready (open - draft), no_pr, merged, closed, frozen.
• health: need_restack, missing_parent, dirty_worktrees (repo-wide, not scoped by --current; null when the dirty check was skipped for having too many worktrees).
• worktrees: linked, idle_slots.
• hygiene: merged_but_local, upstream_gone, stale, stale_days — same ancestry-based classification st sweep uses.
• --ci is opt-in because it makes a network call; without forge auth configured, ci is omitted and ci_unavailable_reason explains why. st stats always exits 0 regardless of CI availability.

st pr / st issue¶

• st pr list --limit 50 --json
• st issue list --limit 50 --json

st generate · st gen¶

• Bare st gen opens an interactive picker (PR body, PR title, commit message).
• --pr-body — refresh the open PR body from the branch diff (PR templates: --template / --no-template).
• --pr-title — refresh the open PR title from the branch diff.
• --commit-msg — amend HEAD with an AI-generated message from the last commit’s patch.
• Shared: --no-prompt / --edit / --agent <name> / --model <name> (--model requires --agent).

st changelog¶

• --tag-prefix release/ios
• --path src/
• find [query] / search [query] — fuzzy-find commits in the selected range; omit query for an interactive picker.
• --find [query] / --search [query] — flag form of the same fuzzy finder.
• --json

st auth¶

• --from-gh / --token <token> / status

st init¶

• --trunk main

st undo / st redo¶

• --yes / --no-push / --quiet

st absorb¶

• --dry-run (preview) · -a (stage all first)

st edit¶

• --yes (skip final confirmation) · --no-verify (skip pre-commit hooks)

st split¶

• --file <pathspec> (or -f "src/api/*" with glob support)
• --hunk (single-commit hunk-based split)