OpenCode Guide
Navigate: Menu

Introduction

Oh My OpenCode

Getting Started

Guides & Integrations

Reference

Comparisons

OpenCode CLI Commands

The OpenCode CLI is the primary way to run OpenCode from your terminal.
It supports interactive sessions, headless automation, server mode, and advanced integrations such as MCP servers and GitHub Actions.
If you are here, you likely want to:
  • run OpenCode without a GUI
  • automate tasks or CI workflows
  • connect real tools via MCP
  • understand what OpenCode can actually do
This page is the authoritative CLI reference.

🚀 Quick Start

Install the CLI and start an interactive session:
npm install -g @opencode/cli
opencode
By default, this launches the TUI (Terminal UI).
To run a single task and exit:
opencode run "Explain how closures work in JavaScript"

⭐ Most Used Commands

Interactive Session (TUI)

opencode
Start OpenCode in the current project directory.
Continue an existing session:
opencode --continue

One-off Task (Fire & Exit)

opencode run "Summarize recent git commits"
Save output to a file:
opencode run "Generate release notes" > release.md

Start a Headless Server

opencode serve
Attach to it from another terminal:
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
This avoids cold starts and enables automation.

Core Execution Modes

OpenCode supports multiple execution styles depending on your workflow.

opencode (TUI)

  • Interactive reasoning
  • Best for exploration and debugging
  • Supports session continuation

opencode run

  • Non-interactive
  • Ideal for scripts, CI, and automation
  • Supports attaching to a running server
Key flags:
--continue, -c
--session, -s
--model, -m provider/model
--file, -f <path>
--format json
--attach <server-url>

opencode serve

Runs OpenCode as a headless API server.
opencode serve --port 4096
Security:
export OPENCODE_SERVER_PASSWORD=your-password
Uses HTTP basic auth (username: opencode).

opencode web

Same as serve, but launches a Web UI automatically.
opencode web

opencode acp

Starts an Agent Client Protocol (ACP) server using stdin/stdout (ND-JSON).
opencode acp
Used for advanced integrations and tooling.

Agent Management

Agents define system prompts, tools, and behavior presets.
opencode agent create
opencode agent list
Use agents to standardize workflows across teams.

Authentication & Providers

Manage credentials for external providers.
opencode auth login
opencode auth list
opencode auth logout
Credentials are stored locally:
~/.local/share/opencode/auth.json

Model Discovery

List available models from configured providers.
opencode models
opencode models anthropic
Advanced options:
opencode models --refresh
opencode models --verbose

MCP (Model Context Protocol)

MCP allows OpenCode to connect to real tools and data sources.

Manage MCP Servers

opencode mcp add
opencode mcp list
opencode mcp auth
opencode mcp debug <name>
opencode mcp logout <name>
MCP enables browser automation, filesystem access, databases, and more.
→ Learn more: Model Context Protocol (MCP)

GitHub Integration

Run OpenCode inside GitHub Actions.
opencode github install
opencode github run
Useful for automated PR reviews, audits, and CI workflows.

Sessions & History

Manage past conversations.
opencode session list
opencode export <session-id>
opencode import <file-or-url>
Control output format:
--format table
--format json

Usage Statistics

View token usage and cost breakdown.
opencode stats
Filter results:
opencode stats --days 7
opencode stats --models 5
opencode stats --project my-project

Upgrade & Uninstall

Upgrade OpenCode:
opencode upgrade
opencode upgrade v0.1.48
Uninstall safely:
opencode uninstall --dry-run
Keep config or data:
opencode uninstall --keep-config --keep-data

Global Flags

Available for all commands:
--help, -h
--version, -v
--log-level DEBUG|INFO|WARN|ERROR
--print-logs

Environment Variables

Core

OPENCODE_CONFIG
OPENCODE_CONFIG_DIR
OPENCODE_SERVER_PASSWORD
OPENCODE_SERVER_USERNAME
OPENCODE_DISABLE_AUTOUPDATE

Experimental

OPENCODE_EXPERIMENTAL
OPENCODE_EXPERIMENTAL_FILEWATCHER
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX
OPENCODE_EXPERIMENTAL_LSP_TOOL

Next Steps