Bright orange card with the title Install OpenCode v1 and v2, then run the CLI, next to a tilted white tile showing an isometric VibeiDE office
All articles

OpenCode CLI install: v1 and v2 commands, setup and basics

OpenCode CLI install for v1 and v2: the curl script, npm, Homebrew, Scoop or WSL, then connect a provider, run /init and learn the main OpenCode CLI commands.

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 free

Quick 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.

Four install routes (curl script, npm install -g, brew install, choco or scoop) each lighting up in turn and joining one opencode command
Whichever installer you use, you end up with the same opencode command.
MethodCommandInstalls
V2 install scriptcurl -fsSL https://opencode.ai/v2/install | bashOpenCode 2
Install scriptcurl -fsSL https://opencode.ai/install | bashOpenCode 1
npmnpm install -g opencode-aiOpenCode 1
Homebrew, OpenCode tap (macOS, Linux)brew install anomalyco/tap/opencodeOpenCode 1
Homebrew, default formulabrew install opencodeOpenCode 2
Arch Linux, official packagesudo pacman -S opencodeOpenCode 2
Arch Linux, AURparu -S opencode-binOpenCode 1
Windows, Chocolateychoco install opencodeOpenCode 1
Windows, Scoopscoop install opencodeOpenCode 1
Misemise use -g github:anomalyco/opencodeOpenCode 2 with mise 2026.10.9 or later, OpenCode 1 on older mise
Dockerdocker run -it --rm ghcr.io/anomalyco/opencode:2.0.0OpenCode 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 opencode command 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.json files into one global ~/.config/opencode/cli.json, migrated on the first V2 start when cli.json does not exist yet.
  • Several config keys are renamed: plugin becomes plugins, provider becomes providers, command becomes commands, agent becomes agents, snapshot becomes snapshots and attachment becomes media.
  • Logging moves from the logLevel config key to the OPENCODE_LOG_LEVEL environment 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 --version

You 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
opencode

Then 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.

Four first-run steps highlighted in turn: /connect adds a provider, /init writes AGENTS.md, Tab switches Plan and Build, then you type the task prompt
The first run in four steps: connect, init, pick an agent, prompt.
  • 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):

Three ways to run OpenCode (the interactive opencode command, opencode run with a prompt, and opencode serve) each sending a dot into the same session and provider box
The terminal UI, one-shot runs and the headless server all use the same sessions and providers.
CommandWhat it does
opencodeStarts the terminal UI
opencode run "prompt"Runs one prompt non-interactively, then exits
opencode serveStarts a headless server for API access
opencode webStarts the headless server with a web interface
opencode attach [url]Attaches a terminal to an already running server
opencode auth login, list, logoutAdds, lists or removes provider credentials
opencode models [provider]Lists the models your providers offer
opencode agent create, listCreates a custom agent or lists available agents
opencode mcp add, listAdds MCP servers or shows their connection status
opencode session listLists 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 statsShows token usage and cost statistics for your sessions
opencode github installInstalls the GitHub agent in a repository
opencode upgrade [target]Updates to the latest or a specific version
opencode uninstallRemoves 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.jsonl

Use 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 opencode command, 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 /connect or opencode auth login, and list models with opencode models.
  • Run /init once per project and commit the generated AGENTS.md.
  • Use Tab to plan in Plan mode before building, and /undo if a build goes wrong.
  • Script it with opencode run and its flags, or run opencode serve and attach to it.
  • Put shared settings in opencode.json, and read the Migrate from V1 guide before moving a config to OpenCode 2.

Share this article

Post on XShare on LinkedIn

Related articles

Necessary cookies support sign-in, security, your language and this choice. Optional categories stay off until accepted.

First-party page views and acquisition measurement, plus Google Analytics 4 (Google Ireland, data may reach the US). Advertising personalization stays off.

With Analytics enabled, retain Google, Microsoft and Reddit ad click identifiers and share download, signup, activation and purchase conversions with the relevant ad provider. No personalized advertising.

Privacy · Cookie inventory