How to Use OpenCode CLI with OpenRouter

Command-line AI coding assistants have changed how developers build software. Instead of context-switching between a browser tab and your IDE, open-source terminal agents allow you to generate code, refactor functions, run tests, and debug errors without ever leaving your terminal.

OpenCode is one of the most powerful, lightweight, Go-based AI coding agents available for the CLI. Out of the box, it offers a fast Terminal User Interface (TUI), native language server protocol (LSP) support, file tracking, and built-in tools for bash execution and code searching.

While OpenCode works with individual API keys from OpenAI or Anthropic, pairing it with OpenRouter gives you access to hundreds of large language models (LLMs) through a single unified API key, automated provider failovers, and flexible pricing control.

Here is a step-by-step guide on how to set up OpenCode CLI and configure it with OpenRouter.

Part 1: Installing and Setting Up OpenCode CLI

Installing OpenCode takes less than a minute across macOS, Linux, or Windows (via WSL).

1. Installation Methods

Choose the package manager or installer that best fits your local setup:

• Universal Shell Script (macOS / Linux):

  Bash

  curl -fsSL https://opencode.ai/install | bash
  

• Node.js (NPM / Bun / Yarn):

  Bash

  npm install -g opencode-ai
  

• Homebrew (macOS / Linux):

  Bash

  brew install anomalyco/tap/opencode
  

• Arch Linux (AUR):

  Bash

  paru -S opencode-bin
  

2. Initializing OpenCode in Your Project

Once installed, navigate to any code repository on your machine:

cd /path/to/your/project

Launch OpenCode by simply running:

opencode

To help the AI agent understand your codebase structure, rules, and style conventions, run the initialization command inside the TUI:

/init

This scans your directory and generates an AGENTS.md (or OpenCode.md) memory file in your project root. Make sure to commit this file to Git so your entire team can share the same AI context!

Part 2: Connecting OpenRouter to OpenCode

By integrating OpenRouter, you can instantly switch between Claude 3.5 Sonnet, DeepSeek V3, OpenAI o3-mini, and open-source models like Llama without managing separate subscriptions or billing accounts.

Step 1: Get Your OpenRouter API Key

1. Sign up or log into OpenRouter.ai.

2. Navigate to Keys in your dashboard and click Create Key.

3. Copy the generated key (it will look like sk-or-v1-...).

Step 2: Authenticate via the Interactive TUI (Easiest Method)

OpenCode provides an interactive /connect command designed for quick setup:

1. Launch OpenCode in your terminal:

   Bash

   opencode
   

2. Type /connect and hit Enter.

3. Search or scroll to select OpenRouter from the provider list.

4. Paste your OpenRouter API key when prompted.

Once connected, type /models in the TUI to browse and set your active default model.

Step 3: Manual Configuration (Alternative Config File Method)

If you prefer configuring environments via JSON or dotfiles, you can explicitly configure OpenRouter in your opencode.json configuration file (located at $HOME/.opencode.json or in your project root):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "~anthropic/claude-sonnet-latest": {},
        "~deepseek/deepseek-r1": {},
        "~google/gemini-2.5-flash": {}
      }
    }
  }
}

Save your key in OpenCode’s local auth store (~/.local/share/opencode/auth.json):

{
  "openrouter": {
    "type": "api",
    "key": "sk-or-v1-your-actual-api-key-here"
  }
}

Part 3: Essential OpenCode Workflows & Features

Now that OpenCode is connected to OpenRouter, here is how to get the most productivity out of your terminal workflow:

1. Interactive TUI Mode

Simply type opencode to enter the interactive mode.

• Fuzzy File Search: Type @ inside the prompt window to attach and reference specific project files (e.g., @src/auth/login.ts).

• Run Shell Commands: OpenCode has a built-in bash tool. It can run your tests, execute build scripts, and install NPM or Python dependencies directly if you grant permission.

• File Operations: It reads, writes, edits, and patches code changes automatically in your working tree.

2. Headless / Non-Interactive CLI Mode

Need a quick answer or script automation without entering full interactive mode? Use the non-interactive run flag:

opencode run "Explain how error handling works in @server.go"

You can also pass specific models directly on the fly:

opencode run -m openrouter/~anthropic/claude-sonnet-latest "Write a React hook for fetching user profile data"

3. OpenRouter Provider Failovers & Routing

One of the best reasons to use OpenRouter inside OpenCode is provider failover. If an upstream API like Anthropic suffers an outage or severe rate limits, OpenRouter automatically routes your request to an operational fallback provider without crashing your agent’s active coding session.

Quick Reference Commands