OpenCode is an open source coding agent that runs in your terminal and works with many model providers. Getting the OpenCode CLI running takes a few minutes: pick an installer, connect a provider, generate an AGENTS.md and give it a task. This guide walks through each step with the exact commands from the official OpenCode documentation, checked again on 9 November 2026, then covers the parts people usually look up next: OpenCode 1 versus OpenCode 2, Windows, Plan and Build, the OpenCode CLI commands, config files, updating and what to check when a first install misbehaves.
Stop juggling terminal tabs.VibeiDE puts every agent in one Grid you can actually read.Try freeQuick answer: for OpenCode 2, the version the official docs now describe, run curl -fsSL https://opencode.ai/v2/install | bash on macOS, Linux or WSL. For OpenCode 1 run curl -fsSL https://opencode.ai/install | bash or npm install -g opencode-ai. Then start opencode in your project, run /connect to add a model provider and /init to create an AGENTS.md.
Install OpenCode
OpenCode ships through several package managers. Any of them gives you an opencode command, but as of November 2026 they no longer all install the same release line, so check the version column before you pick one.
| Method | Command | Installs |
|---|---|---|
| V2 install script | curl -fsSL https://opencode.ai/v2/install | bash | OpenCode 2 |
| Install script | curl -fsSL https://opencode.ai/install | bash | OpenCode 1 |
| npm | npm install -g opencode-ai | OpenCode 1 |
| Homebrew, OpenCode tap (macOS, Linux) | brew install anomalyco/tap/opencode | OpenCode 1 |
| Homebrew, default formula | brew install opencode | OpenCode 2 |
| Arch Linux, official package | sudo pacman -S opencode | OpenCode 2 |
| Arch Linux, AUR | paru -S opencode-bin | OpenCode 1 |
| Windows, Chocolatey | choco install opencode | OpenCode 1 |
| Windows, Scoop | scoop install opencode | OpenCode 1 |
| Mise | mise use -g github:anomalyco/opencode | OpenCode 2 with mise 2026.10.9 or later, OpenCode 1 on older mise |
| Docker | docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0 | OpenCode 2 (the tag the docs show) |
The docs list a modern terminal emulator as a prerequisite, with WezTerm, Alacritty, Ghostty and Kitty as examples, plus API keys or an account for at least one model provider. Once the install finishes, run opencode --version to confirm the command is on your path and to see which release line you got.
OpenCode 1 or OpenCode 2?
There are two release lines. Since early November 2026 the main OpenCode docs describe OpenCode 2, and a Migrate from V1 guide covers the switch. Points from it that save time, as of November 2026:
- Both versions use the
opencodecommand and are no longer installed side by side by default. - Remove a package-managed OpenCode 1 install (npm, Homebrew tap, Scoop and so on) before installing OpenCode 2; the V2 curl installer replaces the V1 binary.
- Terminal client settings move from layered
tui.jsonfiles into one global~/.config/opencode/cli.json, migrated on the first V2 start whencli.jsondoes not exist yet. - Several config keys are renamed:
pluginbecomesplugins,providerbecomesproviders,commandbecomescommands,agentbecomesagents,snapshotbecomessnapshotsandattachmentbecomesmedia. - Logging moves from the
logLevelconfig key to theOPENCODE_LOG_LEVELenvironment variable. - Keep a copy of your V1 setup while you test, and do not point OpenCode 1 at files after converting them to V2-only shapes.
The command examples in the rest of this guide come from OpenCode 1, which most tutorials and the Windows package managers still ship. On OpenCode 2, run opencode --help to check any command that behaves differently.
Installing on Windows
The docs recommend running OpenCode inside WSL on Windows. The curl scripts above are for macOS, Linux and WSL: in Windows PowerShell, curl is an alias for Invoke-WebRequest and there is no bash, so the command fails. Natively, Scoop, Chocolatey and npm install OpenCode 1. The OpenCode 2 docs say Windows package managers are not supported and offer standalone CLI downloads instead (ARM64, x64 and x64 baseline) plus a Desktop installer. Our guide to OpenCode on Windows covers WSL setup, the OpenCode 2 zip and the usual PATH errors step by step.
Installing on Windows: 'bash' is not recognized
The install one-liner is a bash script for macOS and Linux, and PowerShell and CMD have no bash, so on Windows it stops before installing anything. CMD prints 'bash' is not recognized as an internal or external command, operable program or batch file. and PowerShell prints The term 'bash' is not recognized as the name of a cmdlet, function, script file, or operable program. As of November 2026, the native command that works for OpenCode 2 is the npm package listed in the OpenCode README, which needs Node.js:
npm i -g @opencode/cli@latest
opencode --versionYou can also download the standalone Windows zip linked in the docs, or run the curl script inside WSL, where bash exists. The full fix, with all three routes, is in OpenCode on Windows.
Connect a model provider
OpenCode does not include a model, it talks to the providers you connect. Start it, then run the /connect command inside the terminal UI, pick a provider and paste your credentials. OpenCode stores what you enter in ~/.local/share/opencode/auth.json.
From a normal shell you can do the same with opencode auth login, and check what is configured with opencode auth list. The provider list includes OpenAI, Anthropic, GitHub Copilot, the OpenCode pay-as-you-go provider and local servers such as Ollama, LM Studio and llama.cpp. Subscription rules differ by provider and change over time, so check the provider's own terms before you rely on a plan. Our comparison of OpenCode vs Claude Code covers the model access question in more detail.
To see what your connected providers offer, run opencode models. It prints each model as provider/model, which is the format the --model flag and the config file expect. Our guide to OpenCode models covers picking a default, a small model and per-agent models, and OpenCode free models lists the ones that cost nothing right now.
Start in a project and run /init
Change into a repository and start OpenCode:
cd my-project
opencodeThen run /init inside the terminal UI. OpenCode analyzes the project and writes an AGENTS.md file in the project root. The docs recommend committing it, because it gives every future session the same picture of your build commands, layout and conventions. Codex reads the same file name, so a project that already has one for Codex works here too. Our guide to AGENTS.md for Codex explains how to write a good one.
Treat the generated file as a draft. Delete anything obvious, add the commands you actually run, and keep it short, because it is loaded into context in every session.
Plan first, then build
OpenCode has two primary agents and you switch between them with the Tab key.
- Build is the default. All tools are enabled, so it can edit files and run commands.
- Plan is restricted. File edits and shell commands default to
ask, so it can read the code and propose an approach without changing anything.
A good habit for anything bigger than a one-line fix is to start in Plan, read the proposal, correct it, then switch to Build. It is the same idea as Claude Code plan mode: review the approach before any file changes. Two commands help when a build goes the wrong way: /undo reverts the last change and /redo restores it. /share creates a link to a conversation if you want a second opinion.
OpenCode also has built-in subagents that the main agents can call. The docs describe General for multi-step research and parallel work, Explore as a fast read-only agent for searching a codebase, and Scout for reading external documentation and dependencies.
OpenCode CLI commands
The terminal UI is only one way in. The opencode command also has subcommands for scripting, servers, providers, sessions and maintenance. These are the main ones from the CLI reference as they work in OpenCode 1 (November 2026):
| Command | What it does |
|---|---|
opencode | Starts the terminal UI |
opencode run "prompt" | Runs one prompt non-interactively, then exits |
opencode serve | Starts a headless server for API access |
opencode web | Starts the headless server with a web interface |
opencode attach [url] | Attaches a terminal to an already running server |
opencode auth login, list, logout | Adds, lists or removes provider credentials |
opencode models [provider] | Lists the models your providers offer |
opencode agent create, list | Creates a custom agent or lists available agents |
opencode mcp add, list | Adds MCP servers or shows their connection status |
opencode session list | Lists your OpenCode sessions |
opencode export [sessionID] | Exports a session as JSON |
opencode import <file> | Imports a session from a JSON file or share URL |
opencode stats | Shows token usage and cost statistics for your sessions |
opencode github install | Installs the GitHub agent in a repository |
opencode upgrade [target] | Updates to the latest or a specific version |
opencode uninstall | Removes OpenCode and its related files |
Flags worth remembering
A few global flags work with the terminal UI and with opencode run: --continue (or -c) continues the last session, --session (or -s) continues a specific one, --model (or -m) takes a provider/model value and --agent picks an agent. opencode run adds its own: --format json prints raw JSON events, --file (or -f) attaches files to the message, --title names the session, --fork forks a session you continue instead of extending it, --dir sets the directory to run in and --attach sends the prompt to an already running server.
opencode run --model anthropic/claude-sonnet-4-5 "Add input validation to the signup handler and list the files you changed"
opencode run -c "Now add tests for the validation you just wrote"
opencode run --format json "List the TODO comments in src/" > todos.jsonlUse whichever model name your own opencode models output shows. The one above is the example used in the official config docs. If you run many scripted prompts, start opencode serve once and point each opencode run --attach at it, so every call reuses the same running backend.
Configure OpenCode with opencode.json
Settings live in JSON. A global file sits at ~/.config/opencode/opencode.json, and a project file named opencode.json in the repository root overrides it. A minimal OpenCode 1 project config looks like this:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"permission": {
"edit": "ask",
"bash": "ask"
}
}The model key sets the primary model, small_model sets a lighter one for small tasks, and permission controls which tools need your approval. You can also define your own agents as markdown files in .opencode/agents/ for one project or ~/.config/opencode/agents/ for all of them. The file name becomes the agent name, so review.md creates a review agent. OpenCode 2 renames several of these keys (see the list above), so read the configuration reference for your version before copying a config between the two.
Keep it up to date
Run opencode upgrade to update to the latest version, or pass a version number to install a specific one. If you installed through a package manager, updating with that manager keeps things consistent. Watch the release line: brew upgrade on the default formula and pacman -Syu follow OpenCode 2, while the OpenCode tap, npm, Scoop and Chocolatey stay on OpenCode 1. The CLI reference lists every command and flag, and it is the page to check when a flag in this guide behaves differently on your version.
Troubleshooting a first install
If opencode is not found after installing, open a new terminal so your shell reloads its path, and check where your package manager puts global binaries. If you see two installs, for example one from npm and one from Homebrew, remove one so you know which version runs; with the release lines split, two installs can also mean one OpenCode 1 and one OpenCode 2. If /connect finishes but no models appear, run opencode auth list to confirm the credentials were stored, then opencode models to see what that provider exposes. If the terminal UI renders badly, try one of the terminal emulators the docs recommend. On Windows, the OpenCode on Windows guide lists the log, config and cache folders and the fixes for the common errors. And if a command behaves differently from this guide, run opencode --help first: the installed version is the source of truth for its own flags.
Using OpenCode inside VibeiDE
VibeiDE is a desktop app that coordinates the Codex, Claude Code and OpenCode CLIs you already installed, with your own provider accounts. OpenCode runs headless there, with its activity recorded per task, while Codex and Claude Code run in embedded terminals. Each project has its own task queue, and finished work waits in Ready for review until you mark it reviewed. See the OpenCode page or set it up in about three minutes with a 14-day trial and no card.
Common questions
What is the OpenCode CLI?
It is the opencode command: an open source coding agent you run in a terminal. opencode opens its terminal UI, and subcommands such as opencode run, opencode serve and opencode models cover scripting, servers and providers.
How do I install OpenCode v1?
Use curl -fsSL https://opencode.ai/install | bash on macOS, Linux or WSL, or npm install -g opencode-ai, brew install anomalyco/tap/opencode, paru -S opencode-bin, scoop install opencode or choco install opencode. All of these install OpenCode 1 as of November 2026.
How do I install OpenCode v2?
Run curl -fsSL https://opencode.ai/v2/install | bash, or use brew install opencode (the default formula) or sudo pacman -S opencode. Remove a package-managed OpenCode 1 first. On Windows, use WSL or the standalone CLI download, because the docs say Windows package managers are not supported for OpenCode 2.
Do I need an account to use OpenCode?
You need access to at least one model provider. That can be an API key, a supported subscription sign-in, or a local model server, and you add it with /connect.
Where does OpenCode keep my credentials?
In ~/.local/share/opencode/auth.json, according to the provider documentation. Keep that file out of version control.
What is the difference between opencode and opencode run?
opencode opens the interactive terminal UI. opencode run "prompt" sends one prompt without the UI and exits, which is what you want in scripts, git hooks and CI. Add -c to continue the last session or --format json for machine-readable output.
Can I install OpenCode 1 and OpenCode 2 together?
Not by default, because both install the opencode command. Pick one, remove a package-managed OpenCode 1 before installing OpenCode 2, and keep a copy of your V1 config while you test.
How do I install OpenCode on Windows?
Run the install script inside WSL, which the docs recommend, or use scoop install opencode, choco install opencode or npm install -g opencode-ai natively, which install OpenCode 1. For OpenCode 2 natively, download the standalone CLI build. The curl command does not work in PowerShell.
Can I use OpenCode and Codex on the same project?
Yes, both read AGENTS.md. To keep their edits from colliding, give each task its own Git worktree. Our guide to installing the Codex CLI covers the other side of the setup, and OpenCode vs Codex compares the two.
Takeaways
- The V2 script, the default Homebrew formula and the official Arch package install OpenCode 2, the version the main docs now describe.
- The original curl script, npm, the OpenCode Homebrew tap, the AUR package, Chocolatey and Scoop install OpenCode 1; both lines share the
opencodecommand, so choose one. - On Windows, prefer WSL; the curl script does not run in PowerShell, native package managers ship OpenCode 1, and OpenCode 2 comes as a standalone download.
- Connect a provider with
/connectoropencode auth login, and list models withopencode models. - Run
/initonce per project and commit the generatedAGENTS.md. - Use
Tabto plan in Plan mode before building, and/undoif a build goes wrong. - Script it with
opencode runand its flags, or runopencode serveand attach to it. - Put shared settings in
opencode.json, and read the Migrate from V1 guide before moving a config to OpenCode 2.



