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

> Unlock Goose CLI power Discover how to use the Goose command-line interface with our comprehensive guide Leverage the full agent framework via the terminal for efficient management.

- Repository: [goose/goose](https://github.com/aaif-goose/goose)
- Tags: how-to-guide
- Published: 2026-04-07

---

**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](https://github.com/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/commands/run.rs), [`commands/session.rs`](https://github.com/aaif-goose/goose/blob/main/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:

```bash

# Display available sub-commands and global options

goose --help

```

```bash

# Execute a single prompt without starting an interactive session

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

```

```bash

# Start a new interactive chat session

goose session

```

```bash

# Resume the most recent session with full conversation history

goose session --resume --history

```

```bash

# Run a parameterized recipe from a YAML definition

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

```

```bash

# 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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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.