Does Goose Have a Command-Line Interface? Complete CLI Guide

Yes, Goose ships a full-featured command-line interface compiled into the goose binary. The CLI is implemented in the goose-cli crate within the aaif-goose/goose repository and exposes the entire agent framework through a familiar terminal interface.

The Goose command-line interface serves as the primary entry point for users interacting with the AI agent framework. Built with Rust's Clap library for robust argument parsing and Tokio for async execution, the CLI wraps Goose's core crates and provides sub-commands for interactive chat, automated recipes, session management, and gateway operations.

How the Goose CLI Is Structured

Binary Definition and Entry Point

The CLI architecture begins in crates/goose-cli/Cargo.toml, which declares two binary targets: the main goose executable and a helper for generating manpages. The primary entry point at crates/goose-cli/src/main.rs initializes a Tokio runtime, configures logging, and invokes the async cli() function.

According to the source code, main.rs also handles graceful shutdown by conditionally flushing OpenTelemetry telemetry data before the process exits (lines 12-16). This ensures that tracing data is preserved even when the CLI terminates.

Command Parsing with Clap

Argument definitions live in crates/goose-cli/src/cli.rs. The file defines a Cli struct (lines 38-43) that captures top-level options, and a comprehensive Command enum (starting at line 70) that maps user input to specific operations. The Clap derive macros generate help text, shell completions, and validation automatically.

The Command enum covers all major Goose operations:

• run – Execute single prompts in headless mode
• session – Manage interactive chat sessions
• recipe – Execute predefined automation recipes
• schedule – Handle scheduled task execution
• gateway – Configure gateway settings
• term – Terminal-specific utilities
• update – Self-update mechanisms

Bridging the CLI to the Core Framework

Each sub-command handler resides in crates/goose-cli/src/commands/ (e.g., commands/run.rs, commands/session.rs). These handlers construct a CliSession via goose_cli::session::build_session, which wires together:

• The core goose agent library
• Session persistence and history
• Extension loading
• Telemetry and logging infrastructure

This architecture keeps the CLI layer thin while providing full access to Goose's autonomous agent capabilities.

Practical Goose CLI Examples

The following commands demonstrate common workflows after installing the goose binary:

# Display available sub-commands and global options

goose --help

# Execute a single prompt without starting an interactive session

goose run --text "list all .rs files in the current directory"

# Start a new interactive chat session

goose session

# Resume the most recent session with full conversation history

goose session --resume --history

# Run a parameterized recipe from a YAML definition

goose recipe run --recipe my-awesome-repo/hello-world.yaml --param name=alice

# Generate shell completion scripts for bash integration

goose completion bash > /usr/local/etc/bash_completion.d/goose

Summary

• Yes, Goose provides a complete CLI implemented in the goose-cli crate and distributed as the goose binary.
• The entry point at crates/goose-cli/src/main.rs runs an async Tokio runtime with OpenTelemetry support.
• Command parsing uses Clap in crates/goose-cli/src/cli.rs, defining a Cli struct and Command enum covering operations like run, session, recipe, and gateway.
• Sub-command handlers in crates/goose-cli/src/commands/ integrate with the core library via CliSession builders.
• The CLI supports both headless automation (single prompts, recipes) and interactive workflows (resumable sessions with history).

Frequently Asked Questions

How do I install the Goose CLI?

Install the goose binary by compiling the goose-cli crate from the aaif-goose/goose repository. The Cargo.toml defines the binary target, and running cargo build --release -p goose-cli produces the executable. Pre-built binaries may also be available through the repository's release artifacts.

What is the difference between goose run and goose session?

goose run executes a single prompt in headless mode and exits immediately, making it ideal for scripts and automation. goose session starts an interactive REPL-like chat environment that maintains conversation history and can be resumed later using the --resume flag.

Where are session histories stored when using the CLI?

The goose session command persists conversation data through the CliSession builder defined in crates/goose-cli/src/session/. This module interfaces with Goose's core session manager to handle storage locations, though specific paths depend on the underlying session implementation in the core library.

Can I extend the Goose CLI with custom commands?

While the CLI source in crates/goose-cli/src/cli.rs defines a fixed set of sub-commands via the Command enum, you can extend functionality by creating recipes (YAML-defined automation scripts) that the CLI executes via goose recipe run. For deeper integration, you would modify the source in crates/goose-cli/src/commands/ and rebuild the binary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}