CLI Usage

Complete guide to using the Goose command-line interface

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

Recipe Deeplinks

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