10-cli-conventions.md ReferenceJul 17, 2026

CLI conventions

A few behaviors hold across every gs command. There is one set of global output flags for humans and scripts, and one design rule worth stating up front. gs is the only tool that writes to a GitStack repo, so raw git stays read-only. This page documents those flags, the git commands gs forwards straight through, and the utility commands (version, help, skill, ui) that sit outside the stacking workflow.

Global flags#

Every command accepts the same output flags. They are persistent, so they work before or after the subcommand name.

bash

gs [--plain] [--json] [--no-color] [--verbose] [--profile <name>] <command> [args]

Flag	Effect
`--plain`	Stable, uncolored, untruncated output for scripts.
`--json`	Machine-readable JSON instead of the formatted view.
`--no-color`	Drop color but keep the normal layout.
`--verbose`, `-v`	Expand detail the default view collapses.
`--profile <name>`	Run this one command as a named auth profile. See Configuration & files for how profiles resolve.
`--help`, `-h`	Show help for `gs` or the current subcommand.
`--version`	Print the version and exit.

Flag

--plain

Effect

Stable, uncolored, untruncated output for scripts.

Flag

--json

Effect

Machine-readable JSON instead of the formatted view.

Flag

--no-color

Effect

Drop color but keep the normal layout.

Flag

--verbose, -v

Effect

Expand detail the default view collapses.

Flag

--profile <name>

Effect

Run this one command as a named auth profile. See Configuration & files for how profiles resolve.

Flag

--help, -h

Effect

Show help for gs or the current subcommand.

Flag

--version

Effect

Print the version and exit.

Reach for --plain when a shell pipeline reads the output. Columns stay stable and nothing is truncated or recolored, so grep and awk see the same text on every run. Reach for --json when a program consumes the result and you want structured fields for jq. The default view is tuned for reading in a terminal and may truncate or recolor as the window changes.

Flags work in either position

Because the output flags are persistent, gs --plain stack and gs stack --plain do the same thing. Put the flag wherever it is easiest to type.

-v is overloaded

-v is the short form of --verbose on a subcommand, but on its own gs -v prints the version. If you want verbose output, pair -v with a command or spell out --verbose.

Git passthrough commands#

The manifest tracks each review's tip SHA, and every gs write verb keeps it consistent. A raw git commit or git rebase would move SHAs the manifest still points at and corrupt the stack. Raw git stays read-only.

To keep read-only work in one tool, gs forwards the common git read commands straight to git:

Command	Runs
`gs diff`	`git diff`
`gs log`	`git log`
`gs show`	`git show`
`gs blame`	`git blame`
`gs grep`	`git grep`
`gs fetch`	`git fetch`

Command

gs diff

Runs

git diff

Command

gs log

Runs

git log

Command

gs show

Runs

git show

Command

gs blame

Runs

git blame

Command

gs grep

Runs

git grep

Command

gs fetch

Runs

git fetch

Everything after the command name is handed to git unchanged, flags included, so gs log --oneline -20 and gs diff HEAD~2 -- internal/ behave exactly like their git equivalents.

bash

gs log --oneline -10
gs diff --stat HEAD~3

gs <passthrough> --help shows git's manual

Because arguments pass through untouched, gs diff --help runs git diff --help and opens git's own man page, not a gs help screen. For gs behavior, read this page instead.

The write verbs that would desync the manifest are guarded. gs pull, gs rebase, gs merge, gs reset, and a few others do not run git. They print a short message pointing at the gs equivalent, for example gs pull sends you to gs sync and gs rebase to gs amend. When you genuinely need raw git for working-tree work, git itself is still available; record the result with gs commit afterward.

gs remote#

Inspect git remotes without leaving the read-only boundary.

bash

gs remote [-v]
gs remote get-url <name>
gs remote show [name]

gs remote is a passthrough like the others, but it accepts read-only forms only. The allowed calls are gs remote, gs remote -v, gs remote get-url <name>, and gs remote show [name].

bash

gs remote get-url origin

Mutating forms are refused

Anything that would change a remote (add, set-url, remove) is rejected with a message listing the forms gs remote does accept. Use raw git if you must reconfigure a remote directly.

gs version#

Print the version and build metadata.

bash

gs version

gs version prints the version followed by the commit, build date, builder, Go version, and platform, one field per line. It takes no flags of its own.

bash

$ gs version
gs 0.3.1
commit: b2e41f7
built: 2026-08-03T20:41:07Z
built-by: goreleaser
go: go1.26.5
platform: darwin/arm64

For a quick check, gs --version and gs -v print only a single gs version <v> line, which is enough for a script that just needs the number.

gs help#

Show help for gs or any command.

bash

gs help [command]

Form	Shows
`gs help`	The top-level command list (same as `gs --help`).
`gs help <command>`	Help for that command (same as `gs <command> --help`).
`gs help help`	The help command's own usage.

Form

gs help

Shows

The top-level command list (same as gs --help).

Form

gs help <command>

Shows

Help for that command (same as gs <command> --help).

Form

gs help help

Shows

The help command's own usage.

gs help commit and gs commit --help print the same screen, so use whichever reads better in the moment.

Looking for the workflow and refs topics?

For the everyday workflow, read the Getting Started guide. For review, commit, and thread reference syntax, read Reference syntax.

gs skill#

Emit the GitStack agent skill so an AI coding agent reaches for gs instead of raw git.

bash

gs skill install [path]

Flag	Effect
`--force`, `-f`	Overwrite a file you edited or that gs did not write.

Flag

--force, -f

Effect

Overwrite a file you edited or that gs did not write.

gs skill install writes the bundled SKILL.md, the document that teaches an agent such as Claude Code how GitStack works and when to use gs rather than a raw git write. With no path it prints the skill to stdout, so you can pipe or redirect it anywhere. With a path it writes to that file and creates parent directories as needed. If the path is an existing directory or ends in a separator, the skill lands at <path>/gitstack/SKILL.md, the usual skills-directory layout.

bash

gs skill install ~/.claude/skills/

That writes ~/.claude/skills/gitstack/SKILL.md. Running it again over a copy gs wrote needs no flag; add --force to replace a copy you edited. A gs built from source still installs when you ask, and says the copy is a dev copy.

Install it during setup

If an agent works in your repos, install the skill when you install gs. An agent without it falls back on the raw git writes it learned everywhere else, and those bypass the stack tracking. The getting started guide covers this as part of a fresh install.

gs ui#

Open the configured GitStack server UI in your browser.

bash

gs ui [--no-browser]

Flag	Effect
`--no-browser`	Print the URL but do not launch a browser.

Flag

--no-browser

Effect

Print the URL but do not launch a browser.

gs ui reads your saved server address and opens it with the system browser opener (open, xdg-open, or start). It also prints the URL and a sign-in token to stderr, so you can paste the token at /login when the browser session is not signed in. Run gs login first; without saved config the command cannot find the server.

bash

gs ui --no-browser

Use --no-browser on a headless machine or when you would rather copy the URL yourself.

No local daemon

gs ui is a shortcut to gitstack.sh. All UI rendering happens on the server; the CLI just points your browser at the right page.