CLI Flags

What It Does

gsd is invoked from the command line with optional flags and subcommands. Flags control how a session starts — which model to use, whether to resume, whether to run in headless or single-shot mode, or whether to start in an isolated worktree. Subcommands like gsd config, gsd worktree, and gsd headless exit immediately after their task without launching the TUI.

Most day-to-day work happens inside the interactive TUI using slash commands. The CLI flags listed here are for the binary entry point only.

Usage

gsd [options] [message...]
gsd <subcommand> [subcommand-flags]

Getting help:

gsd --help
gsd <subcommand> --help

How It Works

Flags

Flag	Short	Description
--continue	-c	Resume the most recent session for the current directory. Restores conversation history and active auto-mode state.
--worktree [name]	-w	Start in an isolated git worktree. Auto-names the worktree if no name is given. Creates it if it doesn’t exist; resumes it if it does.
--print	-p	Single-shot prompt mode — send a message (positional arg), print the response, exit. No TUI.
--mode <mode>		Output mode for non-interactive use: text (plain), json (structured), rpc (child process), mcp (MCP server).
--model <id>		Override the default model for this session. Model ID depends on the provider (e.g. claude-opus-4-6, gpt-4o).
--no-session		Disable session persistence — conversation history is not saved.
--extension <path>		Load an additional extension from a file path. Can be repeated for multiple extensions.
--append-system-prompt <path>		Append extra text to the system prompt. Accepts a file path (read as UTF-8) or a literal string. Used internally by subagent dispatch.
--tools <a,b,c>		Restrict available tools to a comma-separated list.
--list-models [search]		List available models and exit. Optionally filter by a search term.
--web [path]		Launch browser-only web mode. Optionally specify a project path. Equivalent to gsd web [path].
--version	-v	Print the installed GSD version and exit.
--help	-h	Print help text and exit.

Subcommands

Subcommand	Description
gsd config	Re-run the interactive setup wizard to configure LLM providers, API keys, and tool integrations.
gsd update	Update GSD to the latest version via npm (npm install -g gsd-pi@latest).
gsd sessions	Interactive session picker — list up to 20 saved sessions for the current directory and choose one to resume.
gsd auto [args]	Shorthand for gsd headless auto [args...]. Runs auto-mode without a TUI — pipeable, CI-friendly.
gsd install <source>	Install a package or extension source and run post-install validation.
gsd remove <source>	Remove an installed package source and its settings entry.
gsd list	List installed package sources from user and project settings.
gsd worktree <cmd>	Manage isolated git worktrees for parallel work streams. Alias: gsd wt.
gsd headless	Run /gsd commands without a TUI — for CI, cron jobs, and scripted automation.
gsd web [start|stop] [path]	Start or stop browser-only web mode. Omitting the action defaults to start.

Worktree Subcommands

gsd worktree (or gsd wt) manages the lifecycle of isolated git worktrees. The -w flag creates or resumes a worktree for interactive sessions; gsd worktree subcommands handle merging and cleanup.

Command	Description
list	List all worktrees with status (files changed, commits ahead, dirty state)
merge [name]	Squash-merge a worktree into main and clean up
clean	Remove all worktrees that have been merged or are empty
remove <name>	Remove a worktree. Alias: rm. Use --force to remove with unmerged changes.

Typical lifecycle:

1. gsd -w              Create worktree, start session inside it
2. (work normally)     All changes happen on the worktree branch
3. Ctrl+C              Exit — dirty work is auto-committed
4. gsd -w              Resume where you left off
5. gsd worktree merge  Squash-merge into main when done

Headless Subcommands

gsd headless accepts its own subcommands and flags. The default command is auto. All subcommands (except query) are translated to /gsd <command> and dispatched via RPC to a child session.

Command	Description
auto	Run all queued units continuously (default)
next	Run one unit then stop
status	Show progress dashboard
new-milestone	Create a milestone from a specification document
query	Instant JSON snapshot of state, next dispatch, and costs (~50ms, no LLM)

Headless flags:

Flag	Description
--timeout <ms>	Overall timeout in milliseconds (default: 300000). For new-milestone, the idle timeout is automatically extended to allow for longer pauses between tool calls.
--output-format <fmt>	Output format: text (human-readable, default), json (structured result on stdout at exit), stream-json (JSONL events streamed in real time).
--json	Alias for --output-format stream-json — emit a JSONL event stream to stdout.
--bare	Minimal context mode: skip CLAUDE.md, AGENTS.md, user settings, and user skills. Useful for CI or ecosystem tooling.
--resume <id>	Resume a prior headless session by ID or ID prefix.
--model <id>	Override model for this headless session
--max-restarts <n>	Number of times to restart on crash before giving up (default: 3). Set to 0 to disable restarts.
--supervised	Forward interactive UI requests to an orchestrator via stdout/stdin. Implies --json.
--response-timeout <ms>	Timeout for orchestrator response in supervised mode (default: 30000)
--answers <path>	Pre-supply answers and secrets from a JSON file — useful for unattended CI runs
--events <types>	Filter JSONL output to specific event types (comma-separated). Implies --json.

new-milestone flags:

Flag	Description
--context <path>	Path to a spec or PRD file. Use - for stdin.
--context-text <text>	Inline specification text
--auto	Start auto-mode automatically after milestone creation
--verbose	Show tool calls in progress output

Exit codes for gsd headless:

Code	Meaning
0	Complete — command finished successfully
1	Error or timeout
10	Blocked — command reported a blocker
11	Cancelled — SIGINT or SIGTERM received

gsd install Sources

gsd install accepts several source formats:

gsd install npm:@foo/bar          # npm package
gsd install git:github.com/user/repo  # git repository
gsd install https://github.com/user/repo  # HTTPS URL
gsd install ./local/path          # local path

Use -l / --local to install into project settings instead of user settings.

What Files It Touches

Reads

File	Purpose
~/.gsd/agent/auth.json	API keys and provider credentials
~/.gsd/sessions/<project>/	Saved session data for the current directory

Writes

File	Purpose
~/.gsd/sessions/<project>/	New session data created on each interactive launch
~/.gsd/agent/auth.json	Updated by gsd config when credentials change
.gsd/runtime/headless-context.md	Temporary context file written by gsd headless new-milestone before spawning the RPC child

Examples

Start a new session:

gsd

Resume the last session:

gsd --continue
# or
gsd -c

Pick a past session interactively:

gsd sessions

Use a specific model:

gsd --model claude-opus-4-6

Single-shot prompt (no TUI):

gsd --print "What's the current project status?"
# or
gsd -p "What's the current project status?"

List available models:

gsd --list-models
gsd --list-models sonnet

Run as an MCP server:

gsd --mode mcp

Start in a new auto-named worktree:

gsd -w

Create or resume a named worktree:

gsd -w auth-refactor

Merge a worktree back to main when done:

gsd worktree merge auth-refactor
# or using the alias
gsd wt merge auth-refactor

List all worktrees with status:

gsd worktree list

Remove all merged or empty worktrees:

gsd worktree clean

Remove a specific worktree (using rm alias):

gsd wt rm auth-refactor

Launch web mode:

gsd --web
gsd web start /path/to/project
gsd web stop

Run headless auto-mode (no TUI, exits when done):

gsd headless
# shorthand:
gsd auto
gsd headless --json          # machine-readable JSONL stream
gsd headless --output-format json auto  # structured result on stdout at exit
gsd headless --timeout 60000 # 1-minute timeout

Run headless with minimal context (CI-safe):

gsd headless --bare auto

Resume a prior headless session:

gsd headless --resume abc123 auto

Create a milestone from a spec file, then auto-execute:

gsd headless new-milestone --context spec.md --auto
cat spec.md | gsd headless new-milestone --context -

Run headless with verbose tool call output:

gsd headless new-milestone --context spec.md --verbose

Run headless with pre-supplied answers (unattended CI):

gsd headless --answers answers.json auto

Disable automatic restarts on crash:

gsd headless --max-restarts 0 auto

Filter JSONL output to specific event types:

gsd headless --events agent_end,extension_ui_request auto

Run headless in supervised orchestrator mode:

gsd headless --supervised auto

Instant state snapshot (no LLM call):

gsd headless query

Install an extension:

gsd install npm:@foo/my-extension
gsd install ./local/extension

Re-run setup wizard:

gsd config

Check version:

gsd --version

Related Commands

• /gsd auto — Start auto-mode from inside the TUI
• /gsd next — Step through one unit at a time
• Headless Mode — Full headless reference
• gsd config — Setup wizard for providers and keys
• Keyboard Shortcuts — In-session shortcut keys