opencode

OpenCode CLI & Web Server Guide

Load this skill when the user asks about using opencode as a tool — CLI commands, non-interactive mode, web server, sessions, models, or any opencode <command> usage.

Installation

curl -fsSL https://opencode.ai/install | bash
# Or: npm install -g opencode-ai
# Or: brew install anomalyco/tap/opencode

Global Options

All commands support: --help, --version, --print-logs, --log-level <DEBUG|INFO|WARN|ERROR>, --pure (disable plugins)

Global flags for TUI/server modes: -m <provider/model>, -c / --continue (resume last session), -s <id> / --session (resume specific session), --fork (copy on resume), --agent <name>, --prompt <text>

Non-Interactive Mode: opencode run

Execute opencode without launching the TUI. Ideal for scripting, CI/CD, and automation.

# Basic usage
opencode run "Explain async/await in TypeScript"

# With specific model
opencode run -m anthropic/claude-sonnet-4-20250514 "Refactor this function"

# Attach files to the prompt
opencode run -f src/index.ts "Explain this file"

# Continue last session
opencode run -c "Now add error handling"

# Fork a session (creates copy)
opencode run -c --fork "Try a different approach"

# Output raw JSON events (for piping/processing)
opencode run --format json "List all TODO comments"

# Share the session after completion
opencode run --share "Generate a README"

run Flags

Flag	Description
-m, --model <provider/model>	Model to use
--agent <name>	Agent to use
-c, --continue	Continue last session
-s, --session <id>	Resume specific session
--fork	Fork session before continuing
--share	Share session after completion
--format <default|json>	Output format (default: formatted)
-f, --file <path>	Attach file(s) to message (repeatable)
--title <text>	Title for the session
--attach <url>	Attach to running server (e.g., http://localhost:4096)
-p, --password <pw>	Basic auth password (env: OPENCODE_SERVER_PASSWORD)
-u, --username <user>	Basic auth username (default: opencode)
--dir <path>	Working directory
--port <num>	Local server port (random if omitted)
--variant <level>	Model reasoning effort (e.g., high, max, minimal)
--thinking	Show thinking blocks
-i, --interactive	Run in direct interactive split-footer mode
--dangerously-skip-permissions	Auto-approve non-denied permissions
--command <cmd>	Run a slash command instead of a message

Attaching run to a Server

Avoid MCP cold boot by attaching to a running server:

# Terminal 1: start server
opencode serve

# Terminal 2: run commands against it
opencode run --attach http://localhost:4096 "Fix the lint errors"

Headless Server: opencode serve

Start a headless server without TUI. Other clients (run --attach, web, attach) connect to it.

# Start with defaults (random port, localhost)
opencode serve

# Specify port
opencode serve --port 4096

# Expose on all interfaces
opencode serve --hostname 0.0.0.0 --port 4096

# Enable mDNS discovery
opencode serve --mdns --port 4096

# Allow CORS for specific origins
opencode serve --cors http://localhost:5173 --port 4096

serve Flags

Flag	Default	Description
--port <num>	0 (random)	Port to listen on
--hostname <addr>	127.0.0.1	Bind address
--mdns	false	Enable mDNS service discovery
--mdns-domain <name>	opencode.local	Custom mDNS domain
--cors <origin>	[]	Additional CORS domains (repeatable)

Server REST API

The server exposes a REST API at the bound address. Key endpoints:

• GET /app — Application details
• POST /app/init — Initialize application
• GET /config/providers — List configured providers
• GET /mode — Available modes
• GET /session — List sessions
• POST /session/init — Initialize session
• POST /session/summarize — Summarize session
• POST /session/abort — Abort running session
• DELETE /session/delete — Delete session
• GET /file/read?path=<path> — Read file content
• GET /file/status — Modified files status
• GET /find/file — Search files
• GET /find/symbol — Search symbols
• GET /find — Search text

Authentication: Use -u / -p flags or OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD env vars.

Web Interface: opencode web

Start server and open the web UI in a browser. Same flags as serve.

opencode web
opencode web --port 4096 --hostname 0.0.0.0
opencode web --cors http://localhost:5173

You can attach a TUI to the same web server:

# Terminal 1
opencode web --port 4096

# Terminal 2
opencode attach http://localhost:4096

Attach to Server: opencode attach

Connect a TUI to a running serve or web instance.

opencode attach http://localhost:4096

# With session resume
opencode attach http://localhost:4096 -c

# With specific session
opencode attach http://localhost:4096 -s <session-id>

# With auth
opencode attach http://localhost:4096 -u opencode -p secretpassword

Flag	Description
--dir <path>	Working directory
-c, --continue	Continue last session
-s, --session <id>	Resume specific session
--fork	Fork on resume
-p, --password <pw>	Auth password
-u, --username <user>	Auth username

ACP Server: opencode acp

Start an Agent Client Protocol server (same flags as serve plus --cwd).

opencode acp --port 4096 --cwd /path/to/project

Session Management

# List sessions
opencode session list
opencode session list -n 10 --format json

# Delete a session
opencode session delete <session-id>

# Export session as JSON
opencode export <session-id>
opencode export <session-id> --sanitize  # redact sensitive data

# Import session from file or share URL
opencode import session.json
opencode import https://opencode.ai/share/abc123

Models & Providers

# List all available models
opencode models

# Filter by provider
opencode models anthropic

# Verbose (includes cost info)
opencode models --verbose

# Refresh model cache
opencode models --refresh

# Manage providers
opencode providers list
opencode providers login
opencode providers logout

PR Workflow: opencode pr

Fetch a GitHub PR branch, checkout, and open opencode:

opencode pr 42

GitHub Agent

opencode github install        # Install GitHub agent
opencode github run            # Run the agent
opencode github run --event '{"type":"issues","action":"opened",...}'
opencode github run --token github_pat_...

MCP Servers

opencode mcp add               # Add an MCP server
opencode mcp list              # List servers and status
opencode mcp auth [name]       # Authenticate OAuth MCP server
opencode mcp logout [name]     # Remove OAuth credentials
opencode mcp debug <name>      # Debug OAuth connection

Agent Management

# List agents
opencode agent list

# Create agent
opencode agent create --description "Review code" --mode subagent --tools "read,grep,glob"

# Create with model
opencode agent create -m anthropic/claude-sonnet-4-20250514 --mode primary

# Create at specific path
opencode agent create --path .opencode/agents/reviewer.md

create Flag	Description
--path <dir>	Output directory
--description <text>	What the agent does
--mode <all|primary|subagent>	Agent mode
--tools <list>	Comma-separated permissions: bash,read,edit,glob,grep,webfetch,task,todowrite,websearch,lsp,skill
-m <model>	Model in provider/model format

Stats & Debugging

# Token usage and costs
opencode stats
opencode stats --days 7 --models --project myproject
opencode stats --tools 10

# Debug tools
opencode debug config           # Show resolved config
opencode debug paths            # Global paths (data, config, cache, state)
opencode debug info             # Debug information
opencode debug skill            # List available skills
opencode debug agent <name>     # Show agent config details
opencode debug startup          # Startup timing
opencode debug lsp              # LSP debugging
opencode debug rg               # Ripgrep debugging
opencode debug file             # File system debugging
opencode debug scrap            # List all known projects
opencode debug snapshot         # Snapshot debugging

Database Tools

opencode db                     # Interactive SQLite shell
opencode db "SELECT * FROM session LIMIT 5"  # Run query
opencode db path                # Print database path
opencode db migrate             # Migrate JSON data to SQLite
opencode db --format json "SELECT count(*) FROM message"

Plugins & Extensions

# Install plugin
opencode plugin <npm-module>
opencode plugin <npm-module> --global
opencode plugin <npm-module> --force  # Replace existing version

Upgrade & Uninstall

# Upgrade
opencode upgrade
opencode upgrade 0.1.48
opencode upgrade --method curl

# Uninstall
opencode uninstall --dry-run       # Preview what gets removed
opencode uninstall -c -d -f        # Remove but keep config and data

Shell Completion

opencode completion  # Generate completion script (bash/zsh/fish)

Configuration

Config Files

• Project: .opencode/opencode.json
• Global: ~/.config/opencode/config.json

Server Config (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Environment Variables

Variable	Description
OPENCODE_AUTO_SHARE	Auto-share sessions
OPENCODE_CONFIG	Custom config path
OPENCODE_DISABLE_CLAUDE_CODE	Disable Claude Code compat
OPENCODE_SERVER_PASSWORD	Default auth password
OPENCODE_SERVER_USERNAME	Default auth username

TUI Quick Reference

When using opencode interactively (default, no subcommand):

Key/Command	Action
Tab	Switch Build/Plan mode
Ctrl+X	Leader key for shortcuts
/help	Show help
/init	Create AGENTS.md
/connect	Configure AI provider
/new	New session
/sessions	List sessions
/models	Switch model
/undo / /redo	Git-based undo/redo
/share / /unshare	Share/unshare session
/compact	Compact context
/details	Show details
/thinking	Toggle thinking
/export	Export session
@file	Fuzzy file reference
!command	Execute shell command