Skip to main content
The Goose CLI provides a powerful command-line interface for interacting with AI agents, managing sessions, and running recipes.

​
Installation

Install Goose using the installation script: 
curl -fsSL https://getgoose.ai/install.sh | bash
Or on Windows: 
irm https://getgoose.ai/install.ps1 | iex

​
Initial Setup

Run the configuration command to set up your provider: 
goose configure
This interactive wizard will guide you through:
  • Choosing a provider (OpenRouter, Tetrate, or manual configuration)
  • Setting up API credentials
  • Selecting a model
  • Configuring extensions

​
Core Commands

​
Starting a Session

Start an interactive session: 
goose session start
Start a session in a specific directory: 
goose session start --working-dir /path/to/project
Resume a previous session: 
goose session resume <session-id>

​
Managing Sessions

List all sessions: 
goose session list
List sessions with filters: 
# Filter by working directory
goose session list --working-dir /path/to/project

# Limit results
goose session list --limit 5

# Sort in ascending order
goose session list --ascending

# Output as JSON
goose session list --format json
Example output: 
Available sessions:
abcd1234 - Fix authentication bug - 2026-03-04T10:30:00 - ~/projects/myapp
efgh5678 - Add new feature - 2026-03-03T15:20:00 - ~/projects/myapp
ijkl9012 - Code review - 2026-03-02T09:15:00 - ~/projects/other

​
Exporting Sessions

Export a session to different formats: 
# Export to JSON
goose session export <session-id> --format json --output session.json

# Export to YAML
goose session export <session-id> --format yaml --output session.yaml

# Export to Markdown
goose session export <session-id> --format markdown --output session.md
The markdown export creates a readable conversation history: 
# Session Export: Fix authentication bug

*Total messages: 12*

---

### User:
Can you help me debug the login issue?

### Assistant:
I'll help you investigate the authentication bug...

​
Removing Sessions

Remove sessions by ID: 
goose session remove --session-id abcd1234
Remove by name: 
goose session remove --name "Fix authentication bug"
Remove using regex pattern: 
goose session remove --regex "^test-.*"
Interactive removal (select from list): 
goose session remove

​
Diagnostics

Generate a diagnostics bundle for debugging: 
goose session diagnostics <session-id>
This creates a ZIP file containing:
  • Session data
  • Configuration
  • System information
  • Relevant logs

​
Recipe Commands

Recipes are reusable workflows that automate common tasks.

​
Listing Recipes

View available recipes: 
goose recipe list
Example output: 
Available recipes:
404Portfolio - Create personalized, creative 404 pages - local: recipe.yaml
api-migration - Migrate API endpoints - github: recipes/api-migration.yaml
code-review - Automated code review - github: recipes/code-review.yaml
Verbose output with details: 
goose recipe list --verbose

​
Running Recipes

Run a recipe by name: 
goose run --recipe 404Portfolio
Run with parameters: 
goose recipe deeplink 404Portfolio platform=github username=johndoe

​
Validating Recipes

Validate recipe syntax: 
goose recipe validate recipe.yaml
Successful validation: 
✓ recipe file is valid
Generate a deeplink to open a recipe in Goose Desktop: 
goose recipe deeplink recipe.yaml
Output: 
✓ Generated deeplink for: 404Portfolio
goose://recipe?config=eyJ0aXRsZSI6IjQwNFBvcnRmb2xpbyJ9...
Open recipe directly in desktop app: 
goose recipe open recipe.yaml

​
Configuration Commands

​
Provider Configuration

Reconfigure provider settings: 
goose configure
Select “Configure Providers” to:
  • Change provider (e.g., from OpenAI to Anthropic)
  • Update API keys
  • Select a different model
  • Configure provider-specific settings

​
Extension Management

Add extensions: 
goose configure
Select “Add Extension” and choose:
  • Built-in Extension: Pre-packaged extensions (developer, memory, etc.)
  • Command-line Extension: Run local scripts or commands
  • Remote Extension: Connect to HTTP/MCP servers
Toggle extensions on/off: 
goose configure
Select “Toggle Extensions” to enable/disable without removing. Remove extensions: 
goose configure
Select “Remove Extension” (only disabled extensions can be removed).

​
Settings Configuration

Configure various settings: 
goose configure
Select “goose settings” to configure:
  • goose mode: Auto, Approve, Smart Approve, or Chat
  • Telemetry: Enable/disable anonymous usage data
  • Tool Permission: Set permissions for individual tools
  • Tool Output: Control verbosity (high/medium/all)
  • Max Turns: Maximum autonomous turns
  • Secret Storage: Keyring vs file-based storage
  • Experiments: Toggle experimental features

​
Information Commands

​
System Information

View system and configuration details: 
goose info
Example output: 
Goose v1.26.0
Provider: anthropic
Model: claude-4.5-sonnet
Config: ~/.config/goose/config.yaml
Extensions: developer, memory (2 enabled)

​
Update Check

Check for updates: 
goose update

​
Environment Variables

Key environment variables that affect CLI behavior:
  • GOOSE_PROVIDER: Override configured provider
  • GOOSE_MODEL: Override configured model
  • GOOSE_MODE: Set mode (auto/approve/smart_approve/chat)
  • GOOSE_TELEMETRY_OFF: Disable telemetry (set to 1)
  • GOOSE_CLI_MIN_PRIORITY: Tool output verbosity (0.0-1.0)
  • GOOSE_DISABLE_KEYRING: Use file-based secret storage
See Environment Variables for complete reference.

​
Common Workflows

​
Quick Code Review

1

Start session in project

cd /path/to/project
goose session start
2

Request review

Type your request:
Review the changes in src/auth.rs
3

Export results

goose session export <session-id> --format markdown --output review.md

​
Running a Recipe

1

List available recipes

goose recipe list
2

Validate recipe

goose recipe validate my-recipe.yaml
3

Run recipe

goose run --recipe my-recipe.yaml

​
Tips and Tricks

​
Session Management

  • Use descriptive session names for easy identification
  • Regularly export important sessions for documentation
  • Clean up old sessions with goose session remove

​
Performance

  • Use --format json for scripting and automation
  • Limit session list results with --limit for faster output
  • Use working directory filters to narrow down sessions

​
Debugging

  • Generate diagnostics bundles when reporting issues
  • Check goose info to verify configuration
  • Use verbose mode on recipe list for detailed information

​
Exit Codes

The CLI uses standard exit codes:
  • 0: Success
  • 1: General error
  • 2: Configuration error
  • 3: Network/API error
Use in scripts: 
if goose session list --format json > sessions.json; then
    echo "Sessions exported successfully"
else
    echo "Failed to export sessions" >&2
    exit 1
fi

Build docs developers (and LLMs) love

Get started for freeTalk to us