Core commands¶
Day-to-day commands you'll use most. For the exhaustive list of every command, subcommand, and flag, see the full reference.
Stack view and creation¶
| Command | What it does |
|---|---|
st |
Launch the interactive TUI |
st web [path] |
Open a localhost HTMX web workspace in the browser (127.0.0.1 only) |
st ls |
Show stack with PR, rebase, and metadata-repair status |
st ll |
Like st ls plus PR URLs and detail |
st create <name> / st add <name> |
Create a branch stacked on current |
st create --ai -a --yes |
Generate branch name + first commit message |
st create <name> --below |
Insert a new branch below current, carrying tracked/untracked prepared changes with it |
st get [branch|PR] |
Sync the current stack, or fetch a branch/PR stack from remote without overwriting local commits |
If you discover a hotfix while working upstack, keep the edits in place:
st create cve-hotfix --below
st create --below -am "fix: patch CVE-2026-0001"
--below auto-stashes prepared tracked and untracked changes before moving to the lower base, then reapplies them on the inserted branch. With -am, those changes are staged and committed on the new lower branch.
When -m or --ai derives a branch name that already exists, Stax stops instead of creating a suffixed duplicate; pass an explicit different name or checkout/reparent the existing branch.
Submit and merge¶
| Command | What it does |
|---|---|
st ss |
Submit the whole stack — open or update linked PRs |
st stack link |
Register the current PR stack as a native GitHub Stack when gh-stack is available |
st stack unlink [<stack-number>] |
Unstack a remote native Stack by number, or the active locally tracked stack when omitted |
st branch submit |
Submit only the current branch; if its parent is already synced to the remote, Stax may publish a temporary rebased head without moving your local branch |
st upstack submit |
Submit current branch and descendants; descendants are temporarily chained onto any temporary parent publish heads |
st draft [branch] |
Convert the current (or named) branch's PR to draft |
st draft --stack |
Convert every PR in the current stack to draft |
st undraft [branch] |
Mark the current (or named) branch's PR as ready for review |
st undraft --stack |
Mark every PR in the current stack as ready for review |
st ready |
Interactive PR readiness dashboard — CI, review approval, and merge state for unmerged tracked PRs; auto-refreshes every 15s, drops remotely merged PRs, and stays open until you quit (q) |
st merge |
Cascade-merge from stack bottom up to current branch |
st merge --when-ready |
Wait for CI + approvals, then merge (alias: st mwr) |
st merge --downstack-only / --ds |
Merge ancestors below current, then rebase current branch |
st merge --stack |
Target selected PRs/MRs to trunk and merge the tip with SHA-preserving merge, allowing GitHub or GitLab to mark lower items merged (--full includes descendants); delegates to gh stack merge for atomic landing when the repo has a confirmed-enabled native GitHub Stack and gh-stack v0.1.0+ |
st merge --remote |
Merge remotely via the GitHub API while you keep working |
st merge --all |
Merge the entire stack regardless of where you are |
st cascade |
Restack, push, and create/update PRs in one shot (no trunk fetch; offline-friendly) |
Scoped submit keeps local branch metadata unchanged when it prepares a temporary publish head. Plain git commit work on the branch is included; st restack remains the command that updates local branch tips and parent revisions.
On GitHub repos with native Stacked PRs enabled, st ss/st bs auto-register the submitted PRs with GitHub via gh stack link when the github/gh-stack extension is installed. Repos without access or users without the extension keep the normal stax stack links and see no behavior change. gh-stack v0.0.8+ supports normal GitHub CLI authentication, including token environment variables; stax keeps its token-stripping OAuth fallback only for known older versions. st doctor always reports the installed version and marks versions below v0.1.0 as out of date (v0.1.0 adds gh stack merge for atomic st merge --stack delegation; the legacy-OAuth warning itself still only applies below v0.0.8). st stack unlink <stack-number> delegates to v0.0.8's remote unstack operation without requiring local tracking; omit the number to target the active locally tracked stack. See Native GitHub Stacked PRs.
Sync, restack, update¶
| Command | What it does |
|---|---|
st rs |
Pull trunk, clean merged branches, reparent children — undoable via st undo |
st rs --restack |
rs plus rebase the current stack onto updated trunk |
st rs --delete-upstream-gone |
Also delete local branches whose upstream is gone |
st rs --stash |
Stash the current working tree before sync starts, without prompting; works with --quiet/--json; does NOT auto-confirm branch deletions |
st rs --no-stash |
Fail on a dirty working tree; overrides --force; conflicts with --stash at parse time |
st rs (interactive) |
After fetch + PR refresh, one Sync plan (trunk, merged/upstream-gone branches with PR # when known, optional --restack preview); deletion prompts only when branches are listed; trunk/restack-only uses Continue sync / Cancel sync; skipped with --force, --quiet, or --json |
st rs --dry-run / st rs --plan |
Preview what sync would do — no fetch, no stash, no ref writes (read-only) |
st rs --dry-run --json |
Same as --dry-run but emits a single JSON document (kind: "sync_plan") instead of human text |
st rs --json |
Run sync and emit the result as a versioned JSON document (kind: "sync", schema version 1); implies non-interactive; failures still emit JSON and exit non-zero |
st rs --json --force |
Same as --json but also auto-confirms branch deletions |
st restack |
Rebase current stack onto parents locally (no fetch) |
st refresh |
Sync trunk without merged-branch cleanup, restack, then push and update PRs; does not show the interactive Sync plan prompt (you already chose this workflow) (pass --delete-merged to opt into sync-style cleanup) |
st refresh --all-stacks |
Sync trunk once, then restack and submit every independent stack; requires a clean tree unless --auto-stash-pop is set, and stops at the first conflict |
st refresh --force --yes --no-prompt |
Full refresh flow without sync or submit prompts |
st refresh --verbose |
Same as st refresh, with detailed sync/restack/submit timing |
Branch housekeeping¶
| Command | What it does |
|---|---|
st sweep |
Classify all local branches: merged, upstream-gone, stale, active (read-only) |
st sweep --delete |
Delete merged branches (including tracked merged PRs) and upstream-gone branches with no unique work after confirmation |
st sweep --delete --include-stale |
Also delete stale branches (older than threshold) |
st sweep --delete --force |
Skip confirmation prompt |
st sweep --stale-days 60 |
Override stale threshold (default 30, or branch.stale_days in config) |
st sweep --json |
Machine-readable output of all classified branches |
Navigation and recovery¶
| Command | What it does |
|---|---|
st init |
Initialize stax or reconfigure the trunk |
st undo / st redo |
Rescue or reapply the last risky operation |
st resolve |
AI-resolve an in-progress rebase conflict and continue |
st abort |
Abort an in-progress rebase or conflict resolution |
st detach |
Remove a branch from the stack, reparent its children |
Reporting and utility¶
| Command | What it does |
|---|---|
st standup |
Summarize recent activity (--ai for AI version, --ai --style slack for Slack-ready bullets) |
st pr / st pr body / st pr list / st pr list --ready |
Open current PR in browser · view/edit PR body · list open PRs · live CI/PR readiness |
st issue list |
List open issues |
st changelog |
Generate changelog between refs or fuzzy-find commits with find / --find |
st open |
Open the repository in the browser |
st run <cmd> |
Run a command on each branch in the stack (alias: st test <cmd>) |
st doctor / st doctor --fix |
Check repo/config health; --fix applies safe local repairs after one confirmation |
st demo |
Interactive tutorial — no auth or repo required |
See also: Navigation · Stack health · Full reference
st ready and st pr list --ready open an interactive TUI showing CI status, review approval (e.g. "1 approval", "missing review"), and recommended next action for each unmerged tracked PR. The TUI auto-refreshes every 15s and stays open after CI passes — press q to quit. A PR confirmed remotely merged disappears on initial load or the next refresh; this only updates readiness and cached PR state, and does not delete or reparent local branches (use st sync for cleanup). Closed but unmerged PRs remain visible as fix candidates. Use --current or --stack to limit to the current stack. Use --plain for a single static table (safe for capture/pipes) and --json for the machine-readable readiness schema. Use --interval <secs> to change the auto-refresh interval.