goose/documentation/docs/guides/goose-cli-commands.md

sidebar_position, title, sidebar_label

sidebar_position	title	sidebar_label
7	CLI Commands	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:**

```bash
goose session --name <n>
```

---

Resume a previous session

**Options:**

**`-r, --resume`**

**Usage:**

```bash
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`.
```bash
goose session --resume --id <id>
```

---

Start a session with the specified extension

 **Options:**

 **`--with-extension <command>`**

 **Usage:**

```bash
goose session --with-extension <command>
```

**Examples:**

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

With environment variable:

```bash
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:**

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

**Examples:**

```bash
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:**

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

**Examples:**

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

**Advanced Examples:**

```bash
# 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:**

```bash
goose session --with-builtin <id>
```

**Example:**

```bash
goose session --with-builtin computercontroller
```

---

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

**Options:**

**`--debug`**

**Usage:**

```bash
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:**

```bash
goose session --max-turns 50
```

---

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

**Options:**

**`--max-turns <NUMBER>`**

**Usage:**

```bash
goose session --max-turns 10
```

**Examples:**

```bash
# 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
• -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 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:

• -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)

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

---

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 using a cron job.

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

Options:

• --id <NAME>: A unique ID for the scheduled job (e.g. daily-report)
• --cron "* * * * * *": Specifies when a job should run using a 6-field cron expression represented as a string in the format "seconds minutes hours day-of-month month day-of-week"
• --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', '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/Ansi themes

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

Slash Commands

• /exit or /quit - Exit the session
• /t - Toggle between Light/Dark/Ansi themes
• /t <theme> - Set theme directly (/t light, /t dark, or /t ansi)
• /? or /help - Display the help menu