CLI Usage

The opencode CLI provides both interactive and non-interactive modes for every workflow -- from local development to CI/CD automation.

Interactive Mode

Running opencode without arguments launches the Terminal User Interface (TUI):

opencode

You can optionally specify a project directory:

opencode /path/to/project

Or pass a prompt directly to start a conversation immediately:

opencode "Explain the architecture of this project"

When a prompt is passed as an argument, opencode starts the TUI and sends the prompt right away.

Non-Interactive Mode

Use opencode run to execute prompts without the TUI. This is ideal for scripts, automation, and CI/CD pipelines.

Basic Usage

opencode run "Review the changes in the working directory"

Mode Flag

The --mode flag lets you specify which agent to use:

opencode run "Add user authentication" --mode plan
opencode run "Implement the login endpoint" --mode build

Available modes: build, plan, general, explore, scout, or any custom agent name.

Model Selection

Specify which model to use:

opencode run "Refactor this module" --model claude-sonnet-4-20250514
opencode run "Write unit tests" --model gpt-4o

Output to File

Write the response to a file:

opencode run "Generate API documentation" --output docs/api.md

Working Directory

Run opencode in a specific project directory:

opencode run "Check for type errors" --dir /path/to/project

Provider and Config Override

opencode run "Summarize changes" --provider openai --model gpt-4o --config ./custom-config.json

Attach to Running Server

Attach to an already running opencode server:

opencode run --attach http://localhost:4096 "Explain this codebase"

This sends the prompt to a running opencode serve instance instead of spawning a new one.

Session ID

Continue a specific session:

opencode run --session abc123 "Add error handling"

Headless Server

Start opencode as a headless API server:

opencode serve

This runs opencode as an HTTP server listening on port 4096 by default. Other clients (including the TUI) can attach to it, sharing the same session and context.

Configuration options:

Flag	Default	Description
`--port`	`4096`	Server listening port
`--hostname`	`localhost`	Bind address
`--cors`	unset	CORS origin (e.g., `*`)

Client Attach

Once the server is running, attach a TUI client:

opencode attach http://localhost:4096

Or send prompts non-interactively:

opencode run --attach http://localhost:4096 "Add pagination"

Web Interface

Start opencode with a browser-based UI:

opencode web

This starts an HTTP server and opens the web interface in your default browser. See the Web Interface guide for details.

Agent Management

Create an Agent

Create a new agent interactively:

opencode agent create

This launches a guided setup for defining agent name, system prompt, provider, model, and permitted tools.

List Agents

opencode agent list

Shows all configured agents with their current settings.

Delete an Agent

opencode agent delete <name>

Authentication

Authenticate with opencode services (OpenCode Zen, session sharing, etc.):

opencode auth login

Opens a browser window for authentication.

List Authenticated Accounts

opencode auth list

Logout

opencode auth logout [account-id]

With no arguments, logs out of all accounts.

Models

List Models

List all available models for your configured providers:

opencode models

Filter by provider:

opencode models anthropic
opencode models openai

Refresh Model Cache

Fetch the latest model lists from providers:

opencode models --refresh

Session Management

List Sessions

opencode session list

Outputs a table of all saved sessions with ID, project, model, and timestamp.

Delete a Session

opencode session delete <session-id>

Delete multiple sessions:

opencode session delete abc123 def456

Delete All Sessions

opencode session delete --all

Export Session

Export a session to a file:

opencode export <session-id>

Writes the full session transcript to a file. The filename defaults to the session ID with a .md extension.

Specify an output path:

opencode export <session-id> --output ./exports/session-review.md

Import Session

Import a previously exported session:

opencode import ./exports/session-review.md

Statistics

View token usage and cost estimates:

opencode stats

Output example:

Token Usage
┌──────────────────────────────────────────────┬───────────┬──────────┐
│ Model                                        │  Tokens   │   Cost   │
├──────────────────────────────────────────────┼───────────┼──────────┤
│ claude-sonnet-4-20250514                     │   142,350 │   $2.85  │
│ gpt-4o                                       │    89,200 │   $0.89  │
├──────────────────────────────────────────────┼───────────┼──────────┤
│ Total                                        │   231,550 │   $3.74  │
└──────────────────────────────────────────────┴───────────┴──────────┘

GitHub Integration

Install GitHub Action

opencode github install

Sets up the opencode GitHub Action in your repository.

Run on GitHub

opencode github run

Runs opencode in the context of the current GitHub repository, useful for local testing of GitHub Action workflows.

MCP Management

Add an MCP Server

opencode mcp add my-server --command "npx @myorg/mcp-server"

With environment variables:

opencode mcp add db --command "node" --args "server.js" --env "DB_URL=$DATABASE_URL"

List MCP Servers

opencode mcp list

Register MCP Auth

opencode mcp auth <server-name>

Plugin System

Install a plugin:

opencode plugin <module>

Plugins extend opencode with additional functionality. Available plugins are listed in the Integrations guide.

Debugging

Debug Mode

Run in debug mode to collect troubleshooting information:

opencode debug

This outputs system information, config paths, provider status, and recent logs.

Print Logs

opencode --print-logs

Streams log output to stdout for debugging.

Log Level

Set the log verbosity:

opencode --log-level debug run "test connection"
opencode --log-level trace run "test connection"

Levels: trace, debug, info, warn, error, fatal.

Updating

Check for Updates

opencode upgrade

If a new version is available, it will be downloaded and installed.

Install Specific Version

opencode upgrade 0.6.0

Uninstall

Remove opencode from your system:

opencode uninstall

This removes the binary and configuration files. You'll be prompted to confirm.

Global Flags

These flags work with any command:

Flag	Description
`--help`, `-h`	Show help for the command
`--version`, `-v`	Show version information
`--print-logs`	Print logs to stdout
`--log-level <level>`	Set log verbosity
`--pure`	Disable TUI rendering (plain output)
`--no-color`	Disable colored output

Environment Variables

opencode respects the following environment variables:

Variable	Description
`OPENCODE_API_KEY`	Default API key for provider
`OPENCODE_PROVIDER`	Default provider name
`OPENCODE_MODEL`	Default model name
`OPENCODE_CONFIG`	Path to config file
`OPENCODE_DATA_DIR`	Data directory for sessions, config (default: `~/.local/share/opencode`)
`OPENCODE_HOME`	Config directory (default: `~/.config/opencode`)
`OPENCODE_SERVER_PASSWORD`	HTTP basic auth password for web/serve
`OPENCODE_LOG_LEVEL`	Log level override
`EDITOR`	Editor for /editor and /export commands
`HOME`	User home directory
`XDG_CONFIG_HOME`	XDG config directory
`XDG_DATA_HOME`	XDG data directory

Example usage:

OPENCODE_PROVIDER=openai OPENCODE_MODEL=gpt-4o opencode run "Explain this code"

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid usage
`3`	Configuration error
`4`	Provider/API error
`5`	Permission denied
`130`	Interrupted (Ctrl+C)

Examples

Daily Standup Summary

opencode run "Summarize the changes in today's commits" --dir ./repo --output daily-summary.md

Code Review

opencode run "Review the diff for security vulnerabilities, performance issues, and code style problems" --model claude-sonnet-4-20250514

Generate Tests

opencode run "Write unit tests for all functions in src/utils/ with 80% coverage" --mode plan
opencode run "Implement the tests from the plan" --mode build

CI/CD Pipeline

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anomalyco/opencode-action@v1
        with:
          prompt: "Review this PR for bugs, security issues, and style problems"
          api-key: ${{ secrets.OPENCODE_API_KEY }}
          model: claude-sonnet-4-20250514

Batch Process Multiple Files

for file in src/**/*.ts; do
  opencode run "Add JSDoc comments to $file" --output /dev/null
done

Interactive Mode​

Non-Interactive Mode​

Basic Usage​

Mode Flag​

Model Selection​

Output to File​

Working Directory​

Provider and Config Override​

Attach to Running Server​

Session ID​

Headless Server​

Client Attach​

Web Interface​

Agent Management​

Create an Agent​

List Agents​

Delete an Agent​

Authentication​

Login​

List Authenticated Accounts​

Logout​

Models​

List Models​

Refresh Model Cache​

Session Management​

List Sessions​

Delete a Session​

Delete All Sessions​

Export Session​

Import Session​

Statistics​

GitHub Integration​

Install GitHub Action​

Run on GitHub​

MCP Management​

Add an MCP Server​

List MCP Servers​

Register MCP Auth​

Plugin System​

Debugging​

Debug Mode​

Print Logs​

Log Level​

Updating​

Check for Updates​

Install Specific Version​

Uninstall​

Global Flags​

Environment Variables​

Exit Codes​

Examples​

Daily Standup Summary​

Code Review​

Generate Tests​

CI/CD Pipeline​

Batch Process Multiple Files​