# How to use Goose: a step-by-step guide to the Goose CLI

URL: https://agentvera.dev/en/blog/how-to-use-goose/ · Published: 2026-11-10

How to use Goose, the open source AI agent: install the CLI, run goose configure, pick a mode, add MCP extensions, write AGENTS.md and run recipes.

**In short:**

- Install the Goose CLI with one curl command (or brew install block-goose-cli), let goose configure pick a provider and model, then run goose session inside a project and describe the task.
- Goose starts in auto mode and runs tools without asking. Switch to approve or smart_approve with /mode, or set GOOSE_MODE, before you let it loose on a real repository.
- Project rules go in AGENTS.md or .goosehints, MCP servers are extensions in ~/.config/goose/config.yaml, and goose run --recipe repeats a task from a YAML file.

To use Goose, you install the CLI with `curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash`, answer the `goose configure` questions to choose a provider and a model, then run `goose session` inside a project and describe what you want. **Goose starts in auto mode, so it runs commands without asking until you switch to approve mode.**

This guide covers each step for the Goose CLI as of November 2026 (version 1.58): install, setup, modes, sessions, extensions, instructions files and recipes, plus the mistakes that cost people the most time.

## What Goose is

Goose is a general-purpose AI agent that runs on your machine. It comes as a CLI, a desktop app for macOS, Linux and Windows, and an API, all built in Rust. It is model-agnostic: you bring a provider such as Anthropic, OpenAI, Gemini, OpenRouter or a local model, and Goose does the tool calling, editing and shell work.

Block created Goose and contributed it to the [Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation "Agentic AI Foundation") under the Linux Foundation in December 2025, together with MCP and AGENTS.md. In April 2026 the repository moved to [aaif-goose/goose](https://github.com/aaif-goose/goose "Goose on GitHub") and the docs to [goose-docs.ai](https://goose-docs.ai "Goose documentation"). Older links to `block/goose` and `block.github.io/goose` still redirect. It is released under Apache-2.0, and new versions come out about once a week.

## Step 1: install the CLI

On macOS, Linux, or Git Bash on Windows:

```bash
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
```

On macOS you can use Homebrew instead. The package names still say “block”:

```bash
brew install block-goose-cli        # CLI
brew install --cask block-goose     # desktop app
```

On Windows PowerShell:

```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"; .\download_cli.ps1
```

The Windows binary lands in `%USERPROFILE%\.local\bin`, which you may need to add to `PATH`. Update later with `goose update`. The CLI and the desktop app share one configuration, so providers and extensions you set in one show up in the other.

## Step 2: run goose configure

The first run starts `goose configure` by itself. You get three paths: sign in to OpenRouter, sign in to Tetrate Agent Router Service, or configure manually by choosing a provider, pasting its key and naming a model. Since version 1.54 it also asks which mode to start in.

Keys go into your system keyring (the Keychain on macOS). If there is no keyring, or you set `GOOSE_DISABLE_KEYRING`, they go to a plain-text `secrets.yaml` instead. You can also export them:

```bash
export ANTHROPIC_API_KEY=...
export GOOSE_PROVIDER=anthropic
export GOOSE_MODEL=claude-sonnet-5-5
```

A key written into `config.yaml` is ignored. Run `goose configure` again any time to change the provider, add or toggle extensions, or open the settings for mode and tool permissions.

If you already pay for Claude Code or ChatGPT Plus/Pro, look at [ACP providers](https://goose-docs.ai/docs/guides/acp-providers "Goose ACP providers"): they let Goose use that login instead of an API key.

## Step 3: start a session

```bash
cd my-project
goose session -n checkout-fix
```

Describe the task in plain words. Useful keys and commands inside a session:

- `Ctrl+J` adds a new line; `Ctrl+C` stops the current request, or exits on an empty line.
- `/mode`, `/model`, `/extension` and `/builtin` change the setup without leaving.
- `/compact` shortens the conversation when it gets long; `/clear` starts over.
- `/status` shows the session, including its ID.

To come back later, run `goose session -r -n checkout-fix`. `goose session list` shows every session, and `--fork` copies one so you can try a different direction without losing the original.

## Step 4: choose a mode before real work

Goose has four modes:

| Mode | What it does |
|---|---|
| `auto` (default) | Runs every tool without asking |
| `approve` | Asks before every tool call |
| `smart_approve` | Asks only for calls it rates as risky |
| `chat` | No tools; talk only |

Switch with `/mode approve` in a session, set `GOOSE_MODE`, or pick a default in `goose configure`. For finer control, set permissions per tool in `goose configure`; they are saved in `permission.yaml`. On a repository you care about, start in `approve` or `smart_approve` and loosen it once you trust the setup.

## Step 5: extensions and MCP servers

Extensions are how Goose gets tools, and every MCP server is an extension. The Developer extension (shell and file editing) is on by default. Others built in include Computer Controller, Memory and Auto Visualiser.

To add one for good, run `goose configure` → **Add Extension** and choose a command-line (stdio) or remote (Streamable HTTP) server. For a single session:

```bash
goose session --with-extension "memory:npx -y @modelcontextprotocol/server-memory"
goose session --with-streamable-http-extension https://example.com/mcp
```

Saved extensions live under `extensions:` in `~/.config/goose/config.yaml` (Windows: `%APPDATA%\Block\goose\config\config.yaml`). SSE servers are no longer supported; use Streamable HTTP.

## Step 6: AGENTS.md and .goosehints

Goose reads `AGENTS.md`, then `.goosehints`, at every level from the working folder up to the git root, and picks up nested ones as it works in subfolders. A global file at `~/.config/goose/.goosehints` applies to every project.

If your project already has a `CLAUDE.md`, you don’t need to copy it:

```bash
export CONTEXT_FILE_NAMES='["AGENTS.md", ".goosehints", "CLAUDE.md"]'
```

Keep the file short: the stack, how to run tests, what not to touch, and what “done” means. Our guide to [CLAUDE.md and AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") covers what to put in it.

## Step 7: goose run and recipes

For one-off tasks without a chat, use `goose run`:

```bash
goose run -t "add a unit test for the price formatter"
goose run -i task.md --output-format json
```

A recipe is a YAML file that saves a task with its instructions, extensions and parameters, so a teammate or a scheduled job can repeat it:

```bash
goose run --recipe release-notes.yaml --params version=2.4.0
goose schedule add --schedule-id weekly-notes --cron "0 0 9 * * 1" --recipe-source release-notes.yaml
```

`goose recipe validate` checks a file before you share it. Two other commands worth knowing: `goose review` asks for an AI review of your git diff, and `goose info -v` shows the version and where the config, sessions and logs are.

## Common pitfalls

- **Leaving auto mode on.** The default runs shell commands without asking. Switch modes before the first task on a real repository.
- **Following old docs.** Tutorials from 2025 point to `block/goose` and `block.github.io`. The commands mostly still work, but current docs are at goose-docs.ai.
- **Putting keys in config.yaml.** Goose ignores them there. Use the keyring, `goose configure` or environment variables.
- **Using the deprecated CLI providers.** To run on a Claude Code or ChatGPT login, set up an ACP provider instead.
- **Long sessions.** Auto-compaction keeps the context under control, but a fresh named session per task keeps answers sharper.

## Running Goose next to other CLIs in AgentVera

Goose has its own desktop app, and if Goose is the only agent you use, it may be all you need. It gets harder when Goose runs next to Claude Code, Codex or Gemini CLI on the same project. [AgentVera](/en/ "AgentVera") is a desktop app that runs these CLIs side by side in real terminals, with your own installs and keys. [Goose support](/en/agents/goose/ "Goose in AgentVera") works like this:

- **One named session per agent.** Each Goose agent gets its own session name, and AgentVera reopens it with `goose session --resume --name` on later launches, so the conversation survives an app restart.
- **Your provider and keys.** Goose keeps using the provider from `goose configure`. Under Settings → Accounts you can add API-key accounts (Anthropic, OpenAI, OpenRouter, Google) for Goose agents.
- **Model, effort and role.** The model you pick is passed with `--model`, the effort level through `GOOSE_THINKING_EFFORT`, and the agent’s role with `--system`.
- **MCP and the browser.** Servers from AgentVera’s [MCP manager](/en/features/mcp-manager/ "MCP manager") are passed as `--with-extension` or `--with-streamable-http-extension`, so you set them once for every CLI.
- **Panes, worktrees and review.** Run Goose in the [workspace](/en/features/workspace/ "Workspace") grid next to other agents, each in its own git worktree, and check their changes with code review.

The free plan includes up to 18 agents, MCP, Git, Docker, SSH, code review and token savings. Pro is $9.99 a month; if you have never had a trial, your first sign-in to the app turns on Pro for 7 days with no card. To try it, [download AgentVera](/en/download/ "Download AgentVera").

## Wrapping up

Goose takes three commands to start: install, `goose configure`, `goose session`. The settings that matter most come right after: switch from auto to approve mode, add the extensions you need, and give the project an `AGENTS.md`. Once a task repeats, save it as a recipe.

Sources: [Goose installation](https://goose-docs.ai/docs/getting-started/installation "Install Goose"), [CLI commands](https://goose-docs.ai/docs/guides/goose-cli-commands "Goose CLI commands"), [permissions](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions "Goose permission modes"), [extensions](https://goose-docs.ai/docs/getting-started/using-extensions "Using extensions"), [hints files](https://goose-docs.ai/docs/guides/context-engineering/using-goosehints "Using .goosehints"), [releases](https://github.com/aaif-goose/goose/releases "Goose releases").

## Frequently asked questions

**Is Goose free?** Yes. Goose is open source under the Apache-2.0 license and costs nothing. You pay your model provider for the tokens it uses, or run a local model through Ollama, LM Studio or Docker Model Runner at no token cost.

**Who makes Goose now?** Block created Goose and contributed it to the Agentic AI Foundation (AAIF) under the Linux Foundation in December 2025. Since April 2026 the code lives at github.com/aaif-goose/goose and the docs at goose-docs.ai.

**Can Goose use my Claude Code or ChatGPT subscription?** Yes, through ACP providers, which let Goose drive an existing Claude Code or ChatGPT Plus/Pro login. The older CLI providers that did this are deprecated in favour of ACP providers.

**Does Goose read AGENTS.md or CLAUDE.md?** Goose reads AGENTS.md and then .goosehints at each level from the working folder up to the git root. To also load CLAUDE.md or .cursorrules, add them to the CONTEXT_FILE_NAMES environment variable.

**Does Goose ask before running commands?** Not by default. The default mode is auto, which runs tools without asking. Approve mode asks before every tool call, smart_approve asks only for risky ones, and chat mode turns tools off.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/