Session Command

Start, resume, and manage interactive Goose sessions

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

Usage

goose session [OPTIONS]
goose s [OPTIONS]  # short alias

Basic Examples

Start new session:

goose session

Resume last session:

goose session --resume
goose session -r

Named session:

goose session --name my-project
goose session -n my-project

Resume specific session:

goose session --resume --name my-project
goose session -r -n my-project

Session Identification

--name · string · default: "none"

Name for the chat session. When used with --resume, resumes this specific session if it exists.

Example: --name project-x

--session-id · string · default: "none"

Session ID directly (format: YYYYMMDD_HHMMSS). When used with --resume, resumes this specific session.

Alias: --id

Example: --session-id 20250921_143022

--path · path · default: "none"

Legacy parameter for backward compatibility. Extracts session ID from file path.

Example: --path /path/to/20250325_200615.jsonl

Session Behavior

--resume · 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

--fork · 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

--history · boolean · default: "false"

Show previous messages when resuming a session. Requires --resume.

Example: goose session --resume --history

Session Options

--debug · boolean · default: "false"

Enable debug output mode with full content and no truncation. Shows complete tool responses and full paths.

--max-tool-repetitions · number · default: "none"

Maximum number of consecutive identical tool calls allowed. Helps prevent infinite loops.

Example: --max-tool-repetitions 3

--max-turns · number · default: "1000"

Maximum number of turns allowed without user input.

Example: --max-turns 50

--container · 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

Extension Options

--with-extension · string[] · default: "[]"

Add stdio extensions from full commands with environment variables. Can be specified multiple times.

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

Example:

goose session --with-extension "npx -y @block/gdrive"
goose session --with-extension "API_KEY=xyz node extension.js"

--with-streamable-http-extension · string[] · default: "[]"

Add streamable HTTP extensions from a URL. Can be specified multiple times.

Format: url or url timeout=<seconds>

Example:

goose session --with-streamable-http-extension "http://localhost:8000/messages"
goose session --with-streamable-http-extension "http://api.example.com timeout=300"

--with-builtin · string[] · default: "[]"

Add builtin extensions by name. Multiple extensions can be comma-separated.

Available: developer, autovisualiser, computercontroller, memory, tutorial

Example:

goose session --with-builtin developer
goose session --with-builtin developer,memory,computercontroller

--no-profile · boolean · default: "false"

Don’t load your default extensions, only use CLI-specified extensions.

Example: goose session --no-profile --with-builtin developer

Subcommands

List Sessions

List all available sessions.

goose session list [OPTIONS]

Options:

--format · string · default: "text"

Output format: text or json

--ascending · boolean · default: "false"

Sort by date in ascending order (oldest first). Default is descending (newest first).

--working_dir · path · default: "none"

Filter sessions by working directory.

Short: -w, -p

--limit · number · default: "none"

Limit the number of results.

Short: -l

Example:

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.

goose session remove [OPTIONS]

Options:

--session-id · string · default: "none"

Session ID to remove.

Alias: --id

--name · string · default: "none"

Session name to remove.

Short: -n

--regex · string · default: "none"

Regex pattern for removing matched sessions.

Short: -r

Examples:

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.

goose session export [OPTIONS]

Options:

--output · path · default: "stdout"

Output file path. If not provided, output goes to stdout.

Short: -o

--format · string · default: "markdown"

Output format: markdown, json, or yaml

Examples:

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.

goose session diagnostics [OPTIONS]

Options:

--output · path · default: "diagnostics_<session-id>.zip"

Output path for diagnostics zip file.

Short: -o

Example:

goose session diagnostics --session-id 20250921_143022 -o debug.zip
goose session diagnostics  # Interactive selection

Examples

Development workflow:

# 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:

# Create branch from existing session
goose session --resume --fork --name original-session

Debug mode:

goose session --debug --max-turns 10

Container development:

goose session --container dev-container --with-builtin developer

Remote extensions:

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 - Execute non-interactive sessions
• Configure Command - Manage extensions and settings
• Extensions Overview - Using extensions