How to install and use OpenCode: CLI, TUI, API key, first repo task

Install OpenCode CLI/TUI, attach a key, then finish a first task in a real repo.

You want an open-source agent in the terminal that can read a repo and edit files — without opening another browser chat.

This walkthrough covers how to install and use OpenCode: install the CLI/TUI, sign in or paste an API key with /connect or opencode auth login, then finish a first task in a real repo. Steps follow the Intro, Providers, and CLI pages on opencode.ai/docs.

Who it is for

OpenCode is an open-source terminal agent: opencode with no arguments starts the TUI; the CLI is there too. Desktop and IDE surfaces exist in the docs; this article stays in the terminal. A first run needs a modern terminal emulator plus one working model key.

Install, authenticate, first task

1. 1

   Install the CLI and open the TUI

   On macOS/Linux/WSL run curl -fsSL https://opencode.ai/install | bash, or npm install -g opencode-ai, or brew install anomalyco/tap/opencode (the anomalyco tap is the documented fresher formula). Native Windows can use Chocolatey, Scoop, or npm; full compatibility is documented on WSL. Confirm with opencode --version, then run opencode.

2. 2

   Sign in or add an API key

   In the TUI type /connect. New users can pick OpenCode Zen, sign in at opencode.ai/auth, add billing, and paste the key — or choose OpenAI, Anthropic, or another listed provider. CLI: opencode auth login. Verify with opencode auth list. Keys can also come from the environment or a project .env.

3. 3

   Run a first task in the repo

   cd into the project, run opencode, then /init to write AGENTS.md. First prompt example: “Explain the repo layout in three bullets and suggest one small test I can add.” For a tiny edit, add a one-line comment and keep behavior the same. Read the diff. Use /undo if needed. For scripts, opencode run.

curl -fsSL https://opencode.ai/install | bash
# or: npm install -g opencode-ai
# or: brew install anomalyco/tap/opencode

opencode --version

# Auth (pick one):
# In the TUI:  /connect   → provider or OpenCode Zen → paste API key
# CLI:         opencode auth login
# Check:       opencode auth list
# Keys live in ~/.local/share/opencode/auth.json  (do not commit)

cd /path/to/your/repo
opencode
# In the TUI:  /init     → writes AGENTS.md (ok to commit)
# First task:  Explain the repo layout in three bullets and name one small test I can add
# Small edit:  Add a one-line comment to the main entry file; do not change behavior
# Undo:        /undo

# Non-interactive alternative:
# opencode run "Explain README.md in three bullets and suggest one small test"

What usually blocks a first run

Broken TUI or dead shortcuts

Docs ask for a modern emulator such as WezTerm, Alacritty, Ghostty, or Kitty. If the stock terminal renders poorly, switch first, then debug the model.

Treat auth.json as a password book

Default path is ~/.local/share/opencode/auth.json. Do not copy it into a public repo. If a key already reached Git, rotate it in the vendor console.

Windows feels incomplete

Official guidance is WSL for full compatibility. Chocolatey / Scoop / npm can install a native binary; follow the Windows section.

Official reminder: API calls bill at the vendor or Zen rates. Learn /init and /undo on a cheaper model, then switch to the model you actually want to pay for.

When the diff needs a conversation

After the agent edits, teams often want one picture of what changed. No extra meeting suite. Open a short space on tidemeet or see how to create a space. Canvas: shared whiteboard. Other agent guides: Aider and Codex CLI.

Questions