OpenCode: OpenCode CLI Commands
Last updated: 2026-08-31
--- title: OpenCode CLI Usage description: Master the complete command-line interface including run, serve, agent, and auth commands order: 8 lang: en
OpenCode CLI is not just a TUI launcher—it's a programmable AI development interface.
1. What You Will Learn
- CLI three-layer architecture
- Core command reference
- run command and automation
- Service mode
- Environment variables
2. CLI Three-Layer Architecture
| Layer | Commands | Description |
|---|---|---|
| Interaction | tui / web / attach |
User-facing interfaces |
| Execution | run / agent / mcp / github |
Execute specific tasks |
| Service | serve / acp |
Provide API services |
3. Basic Usage
BASH
# Start TUI (default)
opencode
# Specify project directory
opencode /path/to/project
# Non-interactive mode
opencode run Explain the principle of closures in JavaScript
4. Core Command Reference
| Command | Action | Key Subcommands |
|---|---|---|
agent |
Manage agents | create / list |
auth |
Manage authentication | login / list / logout |
attach |
Connect remote backend | — |
github |
GitHub automation | install / run |
mcp |
MCP service management | add / list / auth / debug |
models |
View model list | — |
run |
Non-interactive execution | — |
serve |
Start API service | — |
web |
Web UI service | — |
session |
Session management | list |
stats |
Token/cost statistics | — |
export |
Export session | — |
import |
Import session | — |
upgrade |
Upgrade version | — |
uninstall |
Uninstall | — |
5. run Command (Most Common)
For non-interactive execution—ideal for scripts and CI/CD:
BASH
opencode run Analyze this Go project's context usage patterns
Common Parameters
| Parameter | Short | Description |
|---|---|---|
--continue |
-c |
Continue session |
--session |
-s |
Specify session |
--model |
-m |
Specify model |
--agent |
— | Specify agent |
--file |
-f |
Attach file |
--format |
— | Output format (json) |
--share |
— | Share session |
--attach |
— | Connect to existing service |
Connect to Background Service
BASH
# Start background service
opencode serve
# Use run with connection
opencode run --attach http://localhost:4096 Explain async/await
6. Other Commands
BASH
# Auth
opencode auth login
opencode auth list
opencode auth logout
# Models
opencode models
opencode models anthropic
opencode models --refresh
# Agent
opencode agent create
opencode agent list
# Serve
opencode serve --port 4096
# Web
opencode web
# Stats
opencode stats --days 7 --models --tools
7. TUI Startup Parameters
| Flag | Short | Description |
|---|---|---|
--continue |
-c |
Continue last session |
--session |
-s |
Specify session ID |
--fork |
— | Fork session |
--prompt |
— | Initial prompt |
--model |
-m |
Specify model |
--agent |
— | Specify agent |
8. Environment Variables
| Variable | Type | Purpose |
|---|---|---|
OPENCODE_AUTO_SHARE |
boolean | Auto-share sessions |
OPENCODE_CONFIG |
string | Custom config path |
OPENCODE_DISABLE_AUTOUPDATE |
boolean | Disable updates |
OPENCODE_SERVER_PASSWORD |
string | API auth password |
OPENCODE_EXPERIMENTAL |
boolean | Enable experimental features |
❓ FAQ
Q Difference between run and TUI?
A run is non-interactive—returns results directly, suited for scripts; TUI is interactive—supports multi-turn conversation and slash commands.
Q How to use OpenCode in CI/CD?
A Start
opencode serve, then use opencode run --attach to connect and execute tasks. Avoids cold starts.Q Alice uses run for code review, Bob uses TUI for development—who's more efficient?
A Each excels in their domain. Alice's run mode suits batch automated review; Bob's TUI suits interactive development. Choose by scenario.
📖 Summary
- CLI three layers: interaction, execution, service
opencode runis the core automation commandopencode serveprovides API service, avoids cold starts- Environment variables suit CI/CD and temporary config
- Daily use TUI, automation use run, high-frequency use serve
📝 Exercises
-
Basic: Use
opencode runfor a non-interactive code analysis. -
Intermediate: Start
opencode serve, then connect viarun --attachto execute a task. -
Advanced: Write a Shell script using
opencode runto auto-analyze project code and generate a report.
