Skip to main content

CLI Commands

Goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. Below is a list of the available commands and their descriptions:

Commands​

help​

Used to display the help menu

Usage:

goose --help

configure [options]​

Configure Goose settings - providers, extensions, etc.

Usage:

goose configure

session [options]​

Start a session and give it a name​

Options:

-n, --name <n>

Usage:

goose session --name <n>

Resume a previous session​

Options:

-r, --resume

Usage:

goose session --resume --name <n>

Or, if you didn't name your session, you can locate it by the session id generated by Goose, e.g. 2025250620_013617.

goose session --resume --id <id>

Start a session with the specified extension​

Options:

--with-extension <command>

Usage:

goose session --with-extension <command>

Examples:

goose session --with-extension "npx -y @modelcontextprotocol/server-memory"

With environment variable:

goose session --with-extension "GITHUB_PERSONAL_ACCESS_TOKEN=<YOUR_TOKEN> npx -y @modelcontextprotocol/server-github"

Start a session with the specified remote extension over SSE​

Options:

--with-remote-extension <url>

Usage:

goose session --with-remote-extension <url>

Examples:

goose session --with-remote-extension "http://localhost:8080/sse"

Start a session with the specified remote extension over Streaming HTTP​

Options:

--with-streamable-http-extension <url>

Usage:

goose session --with-streamable-http-extension <url>

Examples:

goose session --with-streamable-http-extension "https://example.com/streamable"

Advanced Examples:

# Start a session with a streamable HTTP extension
goose session --with-streamable-http-extension "http://api.example.com"

# Use multiple streamable HTTP extensions
goose session \
  --with-streamable-http-extension "http://api1.example.com" \
  --with-streamable-http-extension "http://api2.example.com"

# Mix different extension types
goose session \
  --with-extension "echo hello" \
  --with-remote-extension "http://sse.example.com/sse" \
  --with-streamable-http-extension "http://http.example.com" \
  --with-builtin "developer"

Start a session with the specified built-in extension enabled (e.g. 'developer')​

Options:

--with-builtin <id>

Usage:

goose session --with-builtin <id>

Example:

goose session --with-builtin computercontroller

Enable debug mode to output complete tool responses, detailed parameter values, and full file paths​

Options:

--debug

Usage:

goose session --name my-session --debug

Limit the maximum number of turns the agent can take before asking for user input to continue​

Options:

--max-turns <NUMBER>

Usage:

goose session --max-turns 50

Set the maximum number of turns allowed without user input (default: 1000)​

Options:

--max-turns <NUMBER>

Usage:

goose session --max-turns 10

Examples:

# Low limit for step-by-step control
goose session --max-turns 3

# Moderate limit for controlled automation
goose session --max-turns 25

# Combined with other options
goose session --name my-project --max-turns 10 --debug

session list [options]​

List all saved sessions.

  • -v, --verbose: (Optional) Includes session file paths in the output.
  • -f, --format <format>: Specify output format (text or json). Default is text.
  • --ascending: Sort sessions by date in ascending order (oldest first). Default is descending order (newest first).

Usage:

# List all sessions in text format (default)
goose session list
# List sessions with file paths
goose session list --verbose
# List sessions in JSON format
goose session list --format json
# Sort sessions by date in ascending order.
goose session list --ascending

session remove [options]​

Remove one or more saved sessions.

Options:

  • -i, --id <id>: Remove a specific session by its ID
  • -n, --name <name>: Remove a specific session by its name
  • -r, --regex <pattern>: Remove sessions matching a regex pattern. For example:

Usage:

# Remove a specific session by ID
goose session remove -i 20250305_113223

# Remove a specific session by its name
goose session remove -n my-session

# Remove all sessions starting with "project-"
goose session remove -r "project-.*"

# Remove all sessions containing "migration"
goose session remove -r ".*migration.*"
caution

Session removal is permanent and cannot be undone. Goose will show which sessions will be removed and ask for confirmation before deleting.

session export [options]​

Export a session to Markdown format for sharing, documentation, or archival purposes.

Options:

  • -i, --id <id>: Export a specific session by ID
  • -n, --name <name>: Export a specific session by name
  • -p, --path <path>: Export a specific session by file path
  • -o, --output <file>: Save exported content to a file (default: stdout)

Usage:

# Export specific session to file
goose session export --name my-session --output session.md

# Export specific session to stdout
goose session export --name my-session

# Interactive export (prompts for session selection)
goose session export

# Export session by path
goose session export --path ./my-session.jsonl --output exported.md

info [options]​

Shows Goose information, including the version, configuration file location, session storage, and logs.

  • -v, --verbose: (Optional) Show detailed configuration settings, including environment variables and enabled extensions.

Usage:

goose info

version​

Used to check the current Goose version you have installed

Usage:

goose --version

update [options]​

Update the Goose CLI to a newer version.

Options:

  • --canary, -c: Update to the canary (development) version instead of the stable version
  • --reconfigure, -r: Forces Goose to reset configuration settings during the update process

Usage:

# Update to latest stable version
goose update

# Update to latest canary version
goose update --canary

# Update and reconfigure settings
goose update --reconfigure

mcp​

Run an enabled MCP server specified by <n> (e.g. 'Google Drive')

Usage:

goose mcp <n>

run [options]​

Execute commands from an instruction file or stdin. Check out the full guide for more info.

Options:

  • -i, --instructions <FILE>: Path to instruction file containing commands. Use - for stdin.
  • -t, --text <TEXT>: Input text to provide to Goose directly
  • -s, --interactive: Continue in interactive mode after processing initial input
  • -n, --name <n>: Name for this run session (e.g. daily-tasks)
  • -r, --resume: Resume from a previous run
  • --recipe <RECIPE_FILE_NAME> <OPTIONS>: Load a custom recipe in current session
  • -p, --path <PATH>: Path for this run session (e.g. ./playground.jsonl)
  • --with-extension <COMMAND>: Add stdio extensions (can be used multiple times in the same command)
  • --with-remote-extension <URL>: Add remote extensions over SSE (can be used multiple times in the same command)
  • --with-streamable-http-extension <URL>: Add remote extensions over Streaming HTTP (can be used multiple times in the same command)
  • --with-builtin <n>: Add builtin extensions by name (e.g., 'developer' or multiple: 'developer,github')
  • --debug: Output complete tool responses, detailed parameter values, and full file paths
  • --max-turns <NUMBER>: Maximum number of turns allowed without user input (default: 1000)
  • --explain: Show a recipe's title, description, and parameters
  • --no-session: Run goose commands without creating or storing a session file
  • --max-turns <NUMBER>: Limit the maximum number of turns the agent can take before asking for user input to continue (default: 1000)
  • --provider: Specify the provider to use for this session (overrides environment variable).
  • --model: Specify the model to use for this session (overrides environment variable).

Usage:

goose run --instructions plan.md

#Load a recipe with a prompt that Goose executes and then exits  
goose run --recipe recipe.yaml

#Load a recipe from this chat and then stays in an interactive session
goose run --recipe recipe.yaml -s

#Load a recipe containing a prompt which Goose executes and then drops into an interactive session
goose run --recipe recipe.yaml --interactive

#Generates an error: no text provided for prompt in headless mode
goose run --recipe recipe_no_prompt.yaml

#Load a recipe in debug mode
goose run --recipe recipe.yaml --debug

#Show recipe details
goose run --recipe recipe.yaml --explain

#Run instructions from a file without session storage
goose run --no-session -i instructions.txt

#Run with a limit of 25 turns before asking for user input
goose run --max-turns 25 -i plan.md

#Run with limited turns before prompting user
goose run --recipe recipe.yaml --max-turns 10

#Run with a specified provider and model
goose run --provider anthropic --model claude-4-sonnet -t "initial prompt"

bench​

Used to evaluate system-configuration across a range of practical tasks. See the detailed guide for more information.

Usage:

goose bench ...etc.

recipe​

Used to validate recipe files and manage recipe sharing.

Usage:

goose recipe <COMMAND>

Commands:

  • validate <FILE>: Validate a recipe file
  • deeplink <FILE>: Generate a shareable link for a recipe file

Options:

  • --help, -h: Print help information

Examples:

# Validate a recipe file
goose recipe validate my-recipe.yaml

# Generate a shareable link
goose recipe deeplink my-recipe.yaml

# Get help about recipe commands
goose recipe help

schedule​

Automate recipes by running them on a schedule.

Usage:

goose schedule <COMMAND>

Commands:

  • add <OPTIONS>: Create a new scheduled job. Copies the current version of the recipe to ~/.local/share/goose/scheduled_recipes
  • list: View all scheduled jobs
  • remove: Delete a scheduled job
  • sessions: List sessions created by a scheduled recipe
  • run-now: Run a scheduled recipe immediately

Use the following commands if you're scheduling recipes using the Temporal scheduler (requires the Temporal CLI):

  • services-status: Check if any Temporal services are running
  • services-stop: Stop any running Temporal services

Options:

  • --id <NAME>: A unique ID for the scheduled job (e.g. daily-report)
  • --cron "* * * * * *": Specifies when a job should run using a cron expression represented as a string with either 5, 6, or 7 digits in the format "seconds minutes hours day-of-month month day-of-week year"
  • --recipe-source <PATH>: Path to the recipe YAML file
  • --limit <NUMBER>: (Optional) max number of sessions to display when using the sessions command

Examples:

# Add a new scheduled recipe which runs every day at 9 AM
goose schedule add --id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml

# List all scheduled jobs
goose schedule list

# List the 10 most recent Goose sessions created by a scheduled job
goose schedule sessions --id daily-report --limit 10

# Run a recipe immediately
goose schedule run-now --id daily-report

# Remove a scheduled job
goose schedule remove --id daily-report

project​

Start working on your last project or create a new one.

Alias: p

Usage:

goose project

For a complete guide, see Managing Projects Guide.

projects​

Choose one of your projects to start working on.

Alias: ps

Usage:

goose projects

For detailed usage examples and workflows, see Managing Projects Guide.

web​

Start a new session in Goose Web, a lightweight web-based interface launched via the CLI that mirrors the desktop app's chat experience.

Goose Web is particularly useful when:

  • You want to access Goose with a graphical interface without installing the desktop app
  • You need to use Goose from different devices, including mobile
  • You're working in an environment where installing desktop apps isn't practical

Usage:

goose web

Options:

  • -p, --port <PORT>: Port number to run the web server on. Default is 3000.
  • --host <HOST>: Host to bind the web server to. Default is 127.0.0.1.
  • --open: Automatically open the browser when the server starts.

Examples:

# Start web interface at `http://127.0.0.1:3000` and open the browser
goose web --open

# Start web interface at `http://127.0.0.1:8080` 
goose web --port 8080

# Start web interface accessible from local network at `http://192.168.1.7:8080`
goose web --host 192.168.1.7 --port 8080

Limitations:

While the web interface provides most core features, be aware of these limitations:

  • Some file system operations may require additional confirmation
  • Extension management must be done through the CLI
  • Certain tool interactions might need extra setup
  • Configuration changes require a server restart
warning

Don't expose the web interface to the internet without proper security measures.

info

Use Ctrl-C to stop the server.

Prompt Completion​

The CLI provides a set of slash commands that can be accessed during a session. These commands support tab completion for easier use.

Available Commands​

  • /? or /help - Display this help message
  • /builtin <names> - Add builtin extensions by name (comma-separated)
  • /exit or /quit - Exit the current session
  • /extension <command> - Add a stdio extension (format: ENV1=val1 command args...)
  • /mode <n> - Set the goose mode to use ('auto', 'smart_approve', 'approve', 'chat')
  • /plan <message> - Create a structured plan based on the given message
  • /prompt <n> [--info] [key=value...] - Get prompt info or execute a prompt
  • /prompts [--extension <n>] - List all available prompts, optionally filtered by extension
  • /recipe <recipe file name> - Generate and save a session recipe to recipe.yaml or the filename specified by the command parameter.
  • /summarize - Summarize the current session to reduce context length while preserving key information
  • /t - Toggle between light, dark, and ansi themes
  • /t <theme> - Set the light, dark, or ansi theme

All commands support tab completion. Press <Tab> after a slash (/) to cycle through available commands or to complete partial commands.

Examples​

# Create a plan for triaging test failures
/plan let's create a plan for triaging test failures

# List all prompts from the developer extension
/prompts --extension developer

# Switch to chat mode
/mode chat

Keyboard Shortcuts​

Goose CLI supports several shortcuts and built-in commands for easier navigation.

Keyboard Navigation​

  • Ctrl+C - Interrupt the current request
  • Ctrl+J - Add a newline
  • Cmd+Up/Down arrows - Navigate through command history
  • Ctrl+R - Interactive command history search (reverse search)

The Ctrl+R shortcut provides interactive search through your stored CLI command history. This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, Goose searches backwards through your history for matches.

How it works:

  1. Press Ctrl+R in your Goose CLI session
  2. Type a search term
  3. Navigate through the results using:
    • Ctrl+R to cycle backwards through earlier matches
    • Ctrl+S to cycle forward through newer matches
  4. Press Return (or Enter) to run the found command, or Esc to cancel

For example, instead of retyping this long command:

analyze the performance issues in the sales database queries and suggest optimizations

Use the "sales database" or "optimization" search term to find and rerun it.

Search tips:

  • Distinctive terms work best: Choose unique words or phrases to help filter the results
  • Partial matches and multiple words are supported: You can search for phrases like "gith" and "run the unit test"

Slash Commands​

  • /exit or /quit - Exit the session
  • /t - Toggle between light, dark, and ansi themes
  • /t <theme> - Set the light, dark, or ansi theme
  • /? or /help - Display the help menu

Themes​

The /t command controls the syntax highlighting theme for markdown content in Goose CLI responses. This affects the styles used for headers, code blocks, bold/italic text, and other markdown elements in the response output.

Commands:

  • /t - Cycles through themes: light → dark → ansi → light
  • /t light - Sets light theme (subtle light colors)
  • /t dark - Sets dark theme (subtle darker colors)
  • /t ansi - Sets ansi theme (most visually distinct option with brighter colors)

Configuration:

  • The default theme is dark
  • The theme setting is saved to the configuration file as GOOSE_CLI_THEME and persists between sessions
  • The saved configuration can be overridden for the session using the GOOSE_CLI_THEME environment variable
info

Syntax highlighting styles only affect the font, not the overall terminal interface. The light and dark themes have subtle differences in font color and weight.

The Goose CLI theme is independent from the Goose Desktop theme.

Examples:

# Set ANSI theme for the session via environment variable
export GOOSE_CLI_THEME=ansi
goose session --name use-custom-theme

# Toggle theme during a session
/t

# Set the light theme during a session
/t light