> ## 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. # 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: ```bash theme={null} curl -fsSL https://getgoose.ai/install.sh | bash ``` Or on Windows: ```powershell theme={null} irm https://getgoose.ai/install.ps1 | iex ``` ## Initial Setup Run the configuration command to set up your provider: ```bash theme={null} 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: ```bash theme={null} goose session start ``` Start a session in a specific directory: ```bash theme={null} goose session start --working-dir /path/to/project ``` Resume a previous session: ```bash theme={null} goose session resume ``` ### Managing Sessions List all sessions: ```bash theme={null} goose session list ``` List sessions with filters: ```bash theme={null} # 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: ```bash theme={null} # Export to JSON goose session export --format json --output session.json # Export to YAML goose session export --format yaml --output session.yaml # Export to Markdown goose session export --format markdown --output session.md ``` The markdown export creates a readable conversation history: ```markdown theme={null} # 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: ```bash theme={null} goose session remove --session-id abcd1234 ``` Remove by name: ```bash theme={null} goose session remove --name "Fix authentication bug" ``` Remove using regex pattern: ```bash theme={null} goose session remove --regex "^test-.*" ``` Interactive removal (select from list): ```bash theme={null} goose session remove ``` ### Diagnostics Generate a diagnostics bundle for debugging: ```bash theme={null} goose session diagnostics ``` 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: ```bash theme={null} 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: ```bash theme={null} goose recipe list --verbose ``` ### Running Recipes Run a recipe by name: ```bash theme={null} goose run --recipe 404Portfolio ``` Run with parameters: ```bash theme={null} goose recipe deeplink 404Portfolio platform=github username=johndoe ``` ### Validating Recipes Validate recipe syntax: ```bash theme={null} goose recipe validate recipe.yaml ``` Successful validation: ``` ✓ recipe file is valid ``` ### Recipe Deeplinks Generate a deeplink to open a recipe in Goose Desktop: ```bash theme={null} goose recipe deeplink recipe.yaml ``` Output: ``` ✓ Generated deeplink for: 404Portfolio goose://recipe?config=eyJ0aXRsZSI6IjQwNFBvcnRmb2xpbyJ9... ``` Open recipe directly in desktop app: ```bash theme={null} goose recipe open recipe.yaml ``` ## Configuration Commands ### Provider Configuration Reconfigure provider settings: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} goose configure ``` Select "Toggle Extensions" to enable/disable without removing. Remove extensions: ```bash theme={null} goose configure ``` Select "Remove Extension" (only disabled extensions can be removed). ### Settings Configuration Configure various settings: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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](/guides/environment-variables) for complete reference. ## Common Workflows ### Quick Code Review ```bash theme={null} cd /path/to/project goose session start ``` Type your request: ``` Review the changes in src/auth.rs ``` ```bash theme={null} goose session export --format markdown --output review.md ``` ### Running a Recipe ```bash theme={null} goose recipe list ``` ```bash theme={null} goose recipe validate my-recipe.yaml ``` ```bash theme={null} 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: ```bash theme={null} if goose session list --format json > sessions.json; then echo "Sessions exported successfully" else echo "Failed to export sessions" >&2 exit 1 fi ```