Goose Code CLI Guide

A coding agent from your terminal. The CLI runs on the same core (runOpenAiAgent) as the desktop app: the same loop, the same tool set, the same skills and subagents, the same session files. Only the shell differs - a terminal instead of a window.

The command is called goosecode (short alias - goose). The standalone binary (goose-windows-x64.exe / goose-linux-x64 / goose-macos-arm64) runs without Node/Bun - rename it to whatever suits you. The examples below use goose. From source (dev): bun run cli <args> or bun src/cli/index.ts <args>.

Quick start#

The general form: a command (defaults to run), any options, and an optional prompt. Give a prompt to run one task; omit it to open the interactive REPL.

# Interactive session in the current folder (full-screen UI)
goose

# One-off task: streams the answer and exits
goose "add a dark-mode toggle to the settings page"

# Headless (for scripts/CI): -p / --print
goose -p "explain what src/cli/index.ts does" > notes.md

# Context via stdin
cat build.log | goose -p "why did this build fail?"

# Continue the previous session
goose -c "now write tests for that change"

With no prompt and a terminal attached, an interactive session starts (the full-screen UI by default, or the line-based REPL with --no-ink). With a prompt (an argument and/or stdin) a single non-interactive turn runs instead. See Interactive vs non-interactive for the full breakdown.

Exit codes: 0 - success; 1 - agent error, unknown flag, missing prompt, or missing key. This is what to rely on in CI.

Interactive vs non-interactive#

The CLI picks one of two modes from the way you launch it, and they behave very differently: one keeps a conversation open, the other runs a single task and exits.

# Interactive: the full-screen UI (default)
goose

# Interactive: the classic line-based REPL instead of the full-screen UI
goose --no-ink

# Non-interactive: one task, streamed to stdout, then exit
goose -p "explain what src/cli/index.ts does"

# Non-interactive is also implied by any prompt (even without -p)
goose "add a dark-mode toggle to the settings page"

The -p / --print flag forces non-interactive mode even with no prompt in the arguments - useful when all the input arrives on a pipe.

Authentication and keys#

The CLI is account-only - the same as the desktop app.

A Goose Code key

A gsk_live_… key is created in your account - on the goosecode.org website or in the desktop app (Settings → API Keys). It authenticates your account, usage bills against your subscription (just like in the app), and it's what unlocks the server-mediated tools - web search, page fetching, image analysis and generation (see Which tools are available).

export GOOSE_API_KEY=gsk_live_XXXXXXXXXXXXXXXXXXXX
goose -p "fix the failing test in src/auth"

# or once, as a flag
goose --api-key gsk_live_XXXX -p "explain this repo"

Precedence: --api-key <token> → GOOSE_API_KEY (env). A value beginning with gsk_live_ always goes to the Goose Code proxy.

The run command - the agent#

Runs the agent on a prompt. run is the default command, so goose "prompt" is equivalent to goose run "prompt". The prompt may be an argument, piped in on stdin, or both.

Options:

Models

• goose-ai (default) - the family via account/proxy. The main path.
• auto - the OpenAI tier chain. A provider path, so in a public build it needs an account (a BYO OpenAI key works only in an eval build).
• goose-local - an offline mock agent. No key needed, deterministic output. Good for checking the pipeline, scripts and tests.

# Strongest tier + highest reasoning on a hard refactor
goose -p -m auto --max-effort "refactor the auth module to remove the callback hell"

# Offline check that the CLI works at all
goose -p -m goose-local "hello"

Attach files

--file puts a file into the message context. The core detects the type itself - text, PDF, DOCX, XLSX, an image (images need an account key). A missing path or a directory is an error at startup (better to fail than to silently answer about a file the agent never saw).

goose -p -f error.log -f src/server.ts "why does the server 500 on startup?"
goose -p --file spec.pdf "summarise the API contract in this spec"

An attachment is spent on the first turn (like the app's composer), not glued onto every subsequent one.

Load a skill

--skill loads a skill by name before the turn begins. See the available ones with goose skills.

goose -p -s code-review "review my staged changes"
goose -s react-app "scaffold a settings page with a dark-mode toggle"

A one-off run that leaves no trace

# Writes nothing to the data directory; cannot be resumed
goose -p --no-session-persistence "one-off question - don't save it"

Interrupt

Ctrl-C stops the current turn (the session is kept). A second Ctrl-C at an idle REPL prompt exits.

Interactive session#

Starts when there is no prompt and a terminal is attached: just goose. By default it is a full-screen terminal UI - a composer, live streaming, and a status line. Prefer a classic line-based prompt? Add --no-ink. Both accept the same slash commands:

/help              show help
/new               start a new session
/sessions          list recent sessions
/rm [id]           delete a session (default: the current one)
/model <id>        switch model (auto | goose-ai | goose-local)
/effort            toggle max-effort
/clear             clear the screen
/exit, /quit       leave

Any other /name is treated as a skill invocation of that name (the same as goose skills). For example /code-review inside the REPL runs the code-review skill.

To an agent question (AskUserQuestion) in the REPL you reply with the option number or your own text.

Output formats and automation#

--output-format controls what goes to stdout.

text (default)

A human-readable rendering: assistant text, tool cards, diffs.

json - a single final object

When the turn finishes, exactly one object is printed - the answer and the totals. Handy for a script that wants the result, not a play-by-play.

goose -p -m auto --output-format json "what does src/cli/index.ts export?" | jq -r .result

Object shape:

{
  "type": "result",
  "is_error": false,
  "session_id": "…",
  "num_turns": 3,
  "result": "…answer text…",
  "usage": { "turns": 3, "inputTokens": 1200, "outputTokens": 340, "…": "…" }
}

The usage and error fields are present only when there's something to show (the offline goose-local model, for instance, has no usage). The keys type, is_error, session_id, num_turns, result are always present.

stream-json - an NDJSON stream

A line-by-line stream of events as they happen - one JSON object per line. This is the programmatic contract the eval harness parses.

goose -p -m auto --output-format stream-json "fix the bug" \
  | jq -c 'select(.kind=="block")'

Event kinds (the kind field): message-start, block, usage, error, message-end.

The --json flag is a legacy alias for --output-format stream-json (hidden from --help, but still working; existing scripts and the harness depend on it).

Cap the number of turns

# Don't let an unattended run "keep going until it decides to stop"
goose -p --max-turns 8 "investigate and fix the flaky test"

--max-turns counts main-loop turns (not subagent calls) and only applies in headless mode.

Fail a CI step on an agent error

# is_error → a non-zero exit code
goose -p --output-format json "run the tests and fix any failure" \
  | jq -e '.is_error | not' > /dev/null || exit 1

Sessions#

Lists and deletes saved sessions, which are shared with the app (the same data directory).

list (the default, can be omitted) prints recent sessions; rm <id…> deletes one or more by id. To reopen a session, use -c (latest) or -r <id> on run.

# List (list is the default command, can be omitted)
goose sessions
goose sessions list

# Delete one or more by id
goose sessions rm 8d4e82c9-801d-4110-ad5c-15094f2291cd
goose sessions rm <id1> <id2> <id3>

# Continue the latest / resume a specific one
goose -c "and add a test as well"
goose -r 8d4e82c9-801d-4110-ad5c-15094f2291cd "finish this PR"

Deleting an unknown id is an error (exit 1), not a silent success.

Skills#

Skills are instruction packs, compatible with the Claude Code format. The CLI sees them from several layers (built-ins + ~/.claude/skills/ + <data-dir>/skills/ + <cwd>/.claude/skills/ + <cwd>/.goose/skills/).

Lists the skills visible from the current folder; --json prints them machine-readably. Load one for a run with -s <name>.

# What's available from this folder
goose skills

# Machine-readable
goose skills --json

# Use one in a run
goose -p -s code-review "review the diff on this branch"

In the REPL a skill is invoked as /skill-name [args].

Utility commands#

Examples:

# Build the code index and print stats
goose index
goose index -d src --json

# Check the environment (runtime, ripgrep, tree-sitter, data-dir, flags)
goose doctor

# Launch the desktop app (needs Electron; not available in the standalone exe)
goose open -d ./my-project

Example doctor output:

✓ runtime        bun 1.3.14
✓ electron       …/node_modules/electron/dist/electron.exe
✓ ripgrep        …/@vscode/ripgrep-…/rg.exe
✓ ts runtime     …/web-tree-sitter/tree-sitter.wasm
✓ bash grammar   …/tree-sitter-bash/tree-sitter-bash.wasm
✓ shell parser   tree-sitter
✓ dist build     …/dist
✓ data dir       …/goose-code
✓ workspace      /path/to/project (main)
flags: devtools, telemetry, shell-analysis, context-search, code-index, eval

Environment variables#

Keys and access (public build)

BYO provider keys - eval build only

Effective only if the build carries the eval flag (bun run eval:binary). Ignored in a public build.

Behavior and output

Where things live#

The data directory is shared with the app:

• Windows: %APPDATA%\goose-code
• macOS: ~/Library/Application Support/goose-code
• Linux: $XDG_CONFIG_HOME/goose-code (usually ~/.config/goose-code)

Inside: sessions/ (one file per session), settings.json (shared settings), code-index/ (index cache), skills/ (global skills). The exact path is shown by goose doctor (the data dir line).

Which tools are available in the CLI#

The agent sees the same tool set as the app, minus those that physically cannot run in the current process. Only workable tools are offered to the model - so it doesn't spend a turn on a call that's bound to fail.

Practical upshot: on a Goose Code key everything is available except verify_web. (In an eval build on a BYO provider key, web/vision drop out - they need an account - but the full coding tool set stays.)

Docker / CI#

Use a glibc base image (e.g. debian) - bun-linux-x64 is not built for musl (Alpine).

docker run --rm \
  -e GOOSE_API_KEY \
  -v "$PWD:/work" -w /work \
  debian:stable-slim \
  ./goose-linux-x64 -p "fix the failing test"

The binary extracts its embedded ripgrep into the data directory on first run - no external ripgrep is needed in the container.

An example CI step that fails on an agent error:

goose -p --max-turns 12 --output-format json "make the test suite pass" \
  | tee result.json | jq -e '.is_error | not' > /dev/null

Troubleshooting#