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

---
sidebar_position: 7
title: CLI Commands
sidebar_label: 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:**
```bash
goose --help
```

---

### configure [options]

Configure Goose settings - providers, extensions, etc.

**Usage:**
```bash
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](/docs/getting-started/using-extensions#built-in-extensions) 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](/docs/guides/smart-context-management#maximum-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:**

```bash
# List all sessions in text format (default)
goose session list
```
```bash
# List sessions with file paths
goose session list --verbose
```

```bash
# List sessions in JSON format
goose session list --format json
```
```bash
# 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:**

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

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

---

### version

Used to check the current Goose version you have installed

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

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

---

### run [options]

Execute commands from an instruction file or stdin. Check out the [full guide](/docs/guides/running-tasks) 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](/docs/guides/smart-context-management#maximum-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:**

```bash
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](/docs/tutorials/benchmarking) for more information.

**Usage:**

```bash
goose bench ...etc.
```

### recipe
Used to validate recipe files and manage recipe sharing.

**Usage:**
```bash
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:**
```bash
# 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](/docs/guides/recipes/session-recipes.md#schedule-recipe).

**Usage:**
```bash
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](https://docs.temporal.io/evaluate/development-production-features/schedules) (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](https://en.wikipedia.org/wiki/Cron#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:**
```bash
# 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:**
```bash
goose project
```

For a complete guide, see [Managing Projects Guide](/docs/guides/managing-projects).

---
### projects

Choose one of your projects to start working on.

**Alias**: `ps`

**Usage:**
```bash
goose projects
```

For detailed usage examples and workflows, see [Managing Projects Guide](/docs/guides/managing-projects).

---
### 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:**
```bash
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:**
```bash
# 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`, 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
```bash
# 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`, 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](/docs/guides/config-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](/docs/guides/environment-variables#session-management)

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