> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Command

> Start, resume, and manage interactive Goose sessions

The `session` command starts or resumes interactive chat sessions with Goose.

## Usage

```bash theme={null}
goose session [OPTIONS]
goose s [OPTIONS]  # short alias
```

## Basic Examples

**Start new session:**

```bash theme={null}
goose session
```

**Resume last session:**

```bash theme={null}
goose session --resume
goose session -r
```

**Named session:**

```bash theme={null}
goose session --name my-project
goose session -n my-project
```

**Resume specific session:**

```bash theme={null}
goose session --resume --name my-project
goose session -r -n my-project
```

## Session Identification

<ParamField path="--name" type="string" default="none">
  Name for the chat session. When used with `--resume`, resumes this specific session if it exists.

  **Example:** `--name project-x`
</ParamField>

<ParamField path="--session-id" type="string" default="none">
  Session ID directly (format: `YYYYMMDD_HHMMSS`). When used with `--resume`, resumes this specific session.

  **Alias:** `--id`

  **Example:** `--session-id 20250921_143022`
</ParamField>

<ParamField path="--path" type="path" default="none">
  Legacy parameter for backward compatibility. Extracts session ID from file path.

  **Example:** `--path /path/to/20250325_200615.jsonl`
</ParamField>

## Session Behavior

<ParamField path="--resume" type="boolean" default="false">
  Resume a previous session. If `--name` or `--session-id` provided, resumes that specific session. Otherwise resumes the most recently used session.

  **Short:** `-r`

  **Example:** `goose session --resume --name my-project`
</ParamField>

<ParamField path="--fork" type="boolean" default="false">
  Fork a previous session (creates new session with copied history). Must be used with `--resume`.

  **Example:** `goose session --resume --fork --name old-session`
</ParamField>

<ParamField path="--history" type="boolean" default="false">
  Show previous messages when resuming a session. Requires `--resume`.

  **Example:** `goose session --resume --history`
</ParamField>

## Session Options

<ParamField path="--debug" type="boolean" default="false">
  Enable debug output mode with full content and no truncation. Shows complete tool responses and full paths.
</ParamField>

<ParamField path="--max-tool-repetitions" type="number" default="none">
  Maximum number of consecutive identical tool calls allowed. Helps prevent infinite loops.

  **Example:** `--max-tool-repetitions 3`
</ParamField>

<ParamField path="--max-turns" type="number" default="1000">
  Maximum number of turns allowed without user input.

  **Example:** `--max-turns 50`
</ParamField>

<ParamField path="--container" type="string" default="none">
  Docker container ID to run extensions inside. The extension must exist in the container. For built-in extensions, Goose must be installed in the container.

  **Example:** `--container my-container-id`
</ParamField>

## Extension Options

<ParamField path="--with-extension" type="string[]" default="[]">
  Add stdio extensions from full commands with environment variables. Can be specified multiple times.

  **Format:** `ENV1=val1 ENV2=val2 command args...`

  **Example:**

  ```bash theme={null}
  goose session --with-extension "npx -y @block/gdrive"
  goose session --with-extension "API_KEY=xyz node extension.js"
  ```
</ParamField>

<ParamField path="--with-streamable-http-extension" type="string[]" default="[]">
  Add streamable HTTP extensions from a URL. Can be specified multiple times.

  **Format:** `url` or `url timeout=<seconds>`

  **Example:**

  ```bash theme={null}
  goose session --with-streamable-http-extension "http://localhost:8000/messages"
  goose session --with-streamable-http-extension "http://api.example.com timeout=300"
  ```
</ParamField>

<ParamField path="--with-builtin" type="string[]" default="[]">
  Add builtin extensions by name. Multiple extensions can be comma-separated.

  **Available:** `developer`, `autovisualiser`, `computercontroller`, `memory`, `tutorial`

  **Example:**

  ```bash theme={null}
  goose session --with-builtin developer
  goose session --with-builtin developer,memory,computercontroller
  ```
</ParamField>

<ParamField path="--no-profile" type="boolean" default="false">
  Don't load your default extensions, only use CLI-specified extensions.

  **Example:** `goose session --no-profile --with-builtin developer`
</ParamField>

## Subcommands

### List Sessions

List all available sessions.

```bash theme={null}
goose session list [OPTIONS]
```

**Options:**

<ParamField path="--format" type="string" default="text">
  Output format: `text` or `json`
</ParamField>

<ParamField path="--ascending" type="boolean" default="false">
  Sort by date in ascending order (oldest first). Default is descending (newest first).
</ParamField>

<ParamField path="--working_dir" type="path" default="none">
  Filter sessions by working directory.

  **Short:** `-w`, `-p`
</ParamField>

<ParamField path="--limit" type="number" default="none">
  Limit the number of results.

  **Short:** `-l`
</ParamField>

**Example:**

```bash theme={null}
goose session list --format json --limit 10
goose session list --working_dir ~/projects --ascending
```

### Remove Sessions

Remove sessions. Runs interactively if no ID, name, or regex provided.

```bash theme={null}
goose session remove [OPTIONS]
```

**Options:**

<ParamField path="--session-id" type="string" default="none">
  Session ID to remove.

  **Alias:** `--id`
</ParamField>

<ParamField path="--name" type="string" default="none">
  Session name to remove.

  **Short:** `-n`
</ParamField>

<ParamField path="--regex" type="string" default="none">
  Regex pattern for removing matched sessions.

  **Short:** `-r`
</ParamField>

**Examples:**

```bash theme={null}
goose session remove  # Interactive selection
goose session remove --session-id 20250921_143022
goose session remove --name my-project
goose session remove --regex "^2025.*"
```

### Export Session

Export a session to file or stdout.

```bash theme={null}
goose session export [OPTIONS]
```

**Options:**

<ParamField path="--output" type="path" default="stdout">
  Output file path. If not provided, output goes to stdout.

  **Short:** `-o`
</ParamField>

<ParamField path="--format" type="string" default="markdown">
  Output format: `markdown`, `json`, or `yaml`
</ParamField>

**Examples:**

```bash theme={null}
goose session export --session-id 20250921_143022 --format markdown -o session.md
goose session export --name my-project --format json > session.json
goose session export  # Interactive selection
```

### Generate Diagnostics

Generate diagnostics bundle for a session.

```bash theme={null}
goose session diagnostics [OPTIONS]
```

**Options:**

<ParamField path="--output" type="path" default="diagnostics_<session-id>.zip">
  Output path for diagnostics zip file.

  **Short:** `-o`
</ParamField>

**Example:**

```bash theme={null}
goose session diagnostics --session-id 20250921_143022 -o debug.zip
goose session diagnostics  # Interactive selection
```

## Examples

**Development workflow:**

```bash theme={null}
# Start new project session
goose session --name my-app --with-builtin developer,memory

# Resume later
goose session --resume --name my-app

# Show history
goose session --resume --name my-app --history
```

**Fork existing session:**

```bash theme={null}
# Create branch from existing session
goose session --resume --fork --name original-session
```

**Debug mode:**

```bash theme={null}
goose session --debug --max-turns 10
```

**Container development:**

```bash theme={null}
goose session --container dev-container --with-builtin developer
```

**Remote extensions:**

```bash theme={null}
goose session \
  --with-builtin developer \
  --with-streamable-http-extension "http://localhost:8000/messages" \
  --with-extension "npx -y @block/gdrive"
```

## Session Storage

Sessions are stored in `~/.config/goose/sessions/`:

```
~/.config/goose/sessions/
├── 20250921_143022.jsonl
├── 20250920_091534.jsonl
└── metadata.json
```

Each session is a JSONL file containing the conversation history.

## Environment Variables

Session behavior can be configured via environment:

* `GOOSE_MODE` - Override mode (auto, approve, smart-approve, chat)
* `GOOSE_CLI_MIN_PRIORITY` - Tool output verbosity
* `GOOSE_PROVIDER` - Default provider
* `GOOSE_MODEL` - Default model

## See Also

* [Run Command](/api/cli/recipe) - Execute non-interactive sessions
* [Configure Command](/api/cli/configure) - Manage extensions and settings
* [Extensions Overview](/api/extensions/overview) - Using extensions