Goose Agent Cheatsheet - Providers & Extensions

Goose is a general-purpose terminal AI agent under the Linux Foundation AAIF (Rust, Apache-2.0), for developers and ops who want one capable agent to manipulate local files, run commands, and connect to 15+ model providers and 70+ MCP extensions. Broader than code-focused agents, it fits handing daily automation and cross-tool workflows to a single agent. This sheet covers interactive sessions, one-shot runs, extension management, and goose doctor diagnostics.

AI CLI·30 commands·Last updated 2026-08-21

Session & Run 5

goose session

Start an interactive session (default)

goose session --name feat/login

Name a session for later resume

goose session --resume

Resume the previous session

goose run "Refactor the utils module"

One-shot non-interactive task

goose run --stdin

Read the task from stdin

Configure & Auth 5

goose configure

Interactive provider/key setup

goose configure extensions

Configure extension connections

export GOOSE_PROVIDER=anthropic

Set the provider env var

export GOOSE_MODEL=claude-sonnet

Set the default model

export ANTHROPIC_API_KEY=sk-ant-...

Set the model API key

Extensions (MCP) 5

goose extensions list

List installed extensions

goose extensions add <name>

Add an extension

goose extensions remove <name>

Remove an extension

goose session -e <ext>

Enable an extension for this session

goose configure extensions

Interactive extension config

Recipes & Diagnostics 5

goose cook recipe.yaml

Run a multi-step workflow from a recipe

goose doctor

Diagnose environment/config issues

goose logs

View run logs

goose update

Upgrade Goose to the latest

goose completion bash

Generate shell completion

Serve & Debug 5

goose server start

Start the Goose server

goose server stop

Stop the server

goose server status

Check server status

goose sessions list

List historical sessions

goose chat

Jump straight into chat mode

Global Flags 5

goose run -v "task"

Verbose logging (--verbose)

goose session --session-id <id>

Specify a session ID

goose run --profile prod

Run with a named profile

goose configure --help

Show configure subcommand help

goose --version

Print the version

Command Examples

Name a session so you can resume it by name later

goose session --name feat/login

An unnamed session can only be reached through --resume, which picks the most recent one. As soon as you run two sessions at once, naming is the only reliable way to land on the right one.

Run a one-off task with verbose logging to trace each step

goose run -v "refactor the utils module"

goose run executes a task non-interactively, and -v prints the turn-by-turn trace. If a result looks wrong, re-run once with -v before digging through logs — it is faster than reading them after the fact.

Set provider and model in the current shell, then start a session with one extra extension

export GOOSE_PROVIDER=anthropic
export GOOSE_MODEL=claude-sonnet
export ANTHROPIC_API_KEY=sk-ant-...
goose session -e <ext>

The environment variables only apply to processes started afterwards. The extension passed with -e lives for this session alone and is not written into your extension list.

Run a fixed multi-step workflow from a recipe

goose cook recipe.yaml

A recipe declares its steps declaratively, which makes it a good candidate for committing as a shared team workflow. When a run misbehaves, start with goose doctor to check the environment, then goose logs to see how far the run actually got.

Common Pitfalls

export ANTHROPIC_API_KEY=sk-ant-... leaves the plaintext key sitting in your shell history — never type it by hand on a production box. Store credentials through goose configure into a permission-restricted file instead.
goose extensions remove actually uninstalls the extension rather than disabling it, so any recipe or session that depends on it breaks. Confirm nothing live is using it with goose extensions list first.
Both goose session and goose run may edit files in your workspace. Make sure the tree is clean and committed before you start, and never experiment on the only unpushed copy.
goose server start leaves a resident process holding your provider credentials and a bound port. Shut it down with goose server stop when you are done and confirm with goose server status.
goose logs captures full prompts, file contents, and API responses — scrub them before sharing. goose update replaces the local binary, so exit any running session before you upgrade.

Tips

Goose now sits under Linux Foundation AAIF — Rust + Apache-2.0, 15+ providers and 70+ MCP extensions; rising enterprise adoption makes it a strong "general desktop agent" pick.
Encode recurring flows as recipe.yaml and run with goose cook — more reproducible than retyping prompts, and easy to share with a team.
Set provider/model via env vars (GOOSE_PROVIDER/GOOSE_MODEL) or profiles to switch prod/dev without changing commands.
On environment issues run goose doctor then goose logs — most config/extension problems self-diagnose.

FAQ

How does goose session differ from goose chat, and which one should I use?

goose session opens a full interactive session where the agent can read and write files in your workspace, run commands, and load whatever extensions you enabled. goose chat drops you straight into a conversation-oriented mode that is not meant to touch the filesystem. goose session is the default entry point; reach for goose chat when you only want to talk.

How do I make a multi-step task repeatable instead of retyping the prompt every time?

Write the steps down as a recipe.yaml file and execute it with goose cook recipe.yaml. The same recipe can be re-run as often as you like and committed to the repo so the whole team shares one definition of the workflow, which is far more dependable than re-describing the process in a prompt.

How do I switch models between dev and prod without rewriting the command?

Two options. Either set the shell defaults with export GOOSE_PROVIDER and export GOOSE_MODEL, or pass a profile flag such as goose run --profile prod to run against that profile configuration. Environment variables have to be exported before Goose starts; changing them afterwards does not affect a session that is already open.

How do I load one extra extension for a single session without touching global config?

Add it with goose session -e followed by the extension name. It applies to that session only and disappears when you exit. For durable changes to the extension list, use goose extensions add / remove, or run goose configure extensions for the interactive editor.

How do I pick up where I left off in a previous session?

Run goose sessions list to see every historical session and its ID, goose session --resume to jump straight back into the most recent one, or goose session --session-id with a specific ID to resume a precise session. Restoring the wrong ID silently grafts a new task onto stale context, so list first and then choose.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Maintained by LaoHand

Publicly updated on Aug 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.