Skip to main content
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: --idExample: --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: -rExample: 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, tutorialExample:
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

Build docs developers (and LLMs) love

Get started for freeTalk to us