CLI

// CLI 命令行参考文档 // OpenCode CLI 默认在无参数时启动 TUI（终端用户界面）

OpenCode CLI options and commands.

OpenCode CLI 默认在无参数运行时启动 TUI 终端用户界面。

opencode

同时它也接受以下文档中记录的命令，实现程序化交互。

opencode run "Explain how closures work in JavaScript"

tui

// tui 子命令用于启动终端用户界面 // 这是 OpenCode 的主要交互方式

Start the OpenCode terminal user interface.

opencode [project]

Flags

Flag	Short	Description
`--continue`	`-c`	Continue the last session（继续上一个会话）
`--session`	`-s`	Session ID to continue（指定要继续的会话 ID）
`--fork`	-	Fork the session when continuing（复制会话而非继续）
`--prompt`	-	Prompt to use（自定义提示词）
`--model`	`-m`	Model to use in the form of provider/model（指定模型）
`--agent`	-	Agent to use（指定使用的代理）
`--port`	-	Port to listen on（监听端口）
`--hostname`	-	Hostname to listen on（监听主机名）
`--mdns`	-	Enable mDNS discovery（启用 mDNS 发现）
`--mdns-domain`	-	Custom mDNS domain name（自定义 mDNS 域名）
`--cors`	-	Additional browser origin(s) to allow CORS（允许的额外 CORS 来源）

Commands

// OpenCode CLI 提供的所有子命令 // 涵盖代理管理、认证、MCP、模型、服务器、会话等功能

The OpenCode CLI also has the following commands.

agent

// agent 子命令用于创建和管理自定义代理 // 代理是具有特定系统提示和权限配置的 AI 角色

Manage agents for OpenCode.

opencode agent [command]

create

// create 用于创建新的自定义代理 // 可配置系统提示、权限范围和使用的模型

Create a new agent with custom configuration.

opencode agent create

This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.

Flag	Short	Description
`--path`	-	Directory to write the agent file to（代理文件保存路径）
`--description`	-	What the agent should do（代理职责描述）
`--mode`	-	Agent mode: `all`, `primary`, or `subagent`（代理模式）
`--permissions`	-	Comma-separated list of permissions to allow（允许的工具权限列表）
`--model`	`-m`	Model to use, in `provider/model` format（指定模型）

Available permissions: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill.

list

// list 显示所有已配置的代理

List all available agents.

opencode agent list

attach

// attach 用于连接到运行中的 OpenCode 后端服务器 // 支持远程访问和终端分离使用

Attach a terminal to an already running OpenCode backend server started via serve or web commands.

opencode attach [url]

This allows using the TUI with a remote OpenCode backend.

# Start the backend server for web/mobile access
opencode web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backend
opencode attach http://10.20.30.40:4096

Flag	Short	Description
`--dir`	-	Working directory to start TUI in（工作目录）
`--continue`	`-c`	Continue the last session（继续会话）
`--session`	`-s`	Session ID to continue（指定会话 ID）
`--fork`	-	Fork the session when continuing（复制会话）
`--password`	`-p`	Basic auth password（密码认证）
`--username`	`-u`	Basic auth username（用户名认证）

auth

// auth 子命令用于管理 providers 的 API 密钥 // 凭证存储在 ~/.local/share/opencode/auth.json

Command to manage credentials and login for providers.

opencode auth [command]

// login 命令通过 providers 列表配置 API 密钥 // 支持 models.dev 上的所有 provider

OpenCode is powered by the provider list at Models.dev, so you can use opencode auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/opencode/auth.json.

opencode auth login

Flag	Short	Description
`--provider`	`-p`	Provider ID or name to log in to（指定 provider）
`--method`	`-m`	Login method label to use（登录方式）

list

// list 显示所有已配置的 provider 凭证

Lists all the authenticated providers as stored in the credentials file.

opencode auth list
# Or the short version
opencode auth ls

logout

// logout 清除指定 provider 的凭证

Logs you out of a provider by clearing it from the credentials file.

opencode auth logout

github

// github 子命令用于管理 GitHub 集成代理 // 可在仓库中安装 GitHub Actions 工作流

Manage the GitHub agent for repository automation.

opencode github [command]

install

// install 在仓库中安装 GitHub Actions 工作流

Install the GitHub agent in your repository.

opencode github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process.

run

// run 在 GitHub Actions 环境中运行 GitHub 代理

Run the GitHub agent. This is typically used in GitHub Actions.

opencode github run

Flag	Description
`--event`	GitHub mock event to run the agent for（模拟事件数据）
`--token`	GitHub personal access token（访问令牌）

mcp

// mcp 子命令用于管理 Model Context Protocol 服务器 // MCP 是一种标准化协议，用于扩展 AI 工具能力

Manage Model Context Protocol servers.

opencode mcp [command]

add

// add 交互式添加 MCP 服务器配置

Add an MCP server to your configuration.

opencode mcp add

list

// list 显示所有已配置的 MCP 服务器及其状态

List all configured MCP servers and their connection status.

opencode mcp list
# Or the short version
opencode mcp ls

auth

// auth 处理需要 OAuth 认证的 MCP 服务器

Authenticate with an OAuth-enabled MCP server.

opencode mcp auth [name]

List OAuth-capable servers:

opencode mcp auth list
# Or the short version
opencode mcp auth ls

logout

// logout 清除 MCP 服务器的 OAuth 凭证

Remove OAuth credentials for an MCP server.

opencode mcp logout [name]

debug

// debug 用于排查 OAuth 连接问题

Debug OAuth connection issues for an MCP server.

opencode mcp debug <name>

models

// models 子命令列出所有可用的模型 // 用于确定配置文件中使用的正确模型名称

List all available models from configured providers.

opencode models [provider]

This command displays all models available across your configured providers in the format provider/model.

opencode models anthropic

Flag	Description
`--refresh`	Refresh the models cache from models.dev（刷新模型列表）
`--verbose`	Use more verbose model output (includes metadata like costs)（详细输出）

run

// run 在非交互模式下执行 prompt // 适用于脚本化、自动化或快速查询

Run opencode in non-interactive mode by passing a prompt directly.

opencode run [message..]

opencode run Explain the use of context in Go

You can also attach to a running opencode serve instance:

# Start a headless server in one terminal
opencode serve
# In another terminal, run commands that attach to it
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flag	Short	Description
`--command`	-	The command to run, use message for args
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`	-	Fork the session when continuing
`--share`	-	Share the session
`--model`	`-m`	Model to use in the form of provider/model
`--agent`	-	Agent to use
`--file`	`-f`	File(s) to attach to message
`--format`	-	Format: default (formatted) or json (raw JSON events)
`--title`	-	Title for the session
`--attach`	-	Attach to a running opencode server
`--password`	`-p`	Basic auth password
`--username`	`-u`	Basic auth username
`--dir`	-	Directory to run in, or path on the remote server when attaching
`--port`	-	Port for the local server
`--variant`	-	Model variant (provider-specific reasoning effort)
`--thinking`	-	Show thinking blocks
`--dangerously-skip-permissions`	-	Auto-approve permissions (dangerous!)

serve

// serve 启动无头 HTTP 服务器 // 用于 API 访问，不带 TUI 界面

Start a headless OpenCode server for API access.

opencode serve

This starts an HTTP server that provides API access to opencode functionality without the TUI interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth.

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

session

// session 子命令用于管理会话 // 可列出、删除和导出历史会话

Manage OpenCode sessions.

opencode session [command]

list

// list 显示所有会话，按最近时间排序

List all OpenCode sessions.

opencode session list

Flag	Short	Description
`--max-count`	`-n`	Limit to N most recent sessions
`--format`	-	Output format: table or json

delete

// delete 删除指定会话及其相关数据

Delete an OpenCode session.

opencode session delete <sessionID>

stats

// stats 显示令牌使用量和成本统计 // 帮助跟踪 API 消费情况

Show token usage and cost statistics for your OpenCode sessions.

opencode stats

Flag	Description
`--days`	Show stats for the last N days
`--tools`	Number of tools to show
`--models`	Show model usage breakdown
`--project`	Filter by project

export

// export 将会话数据导出为 JSON // 可用于备份或迁移

Export session data as JSON.

opencode export [sessionID]

Flag	Description
`--sanitize`	Redact sensitive transcript/file data

import

// import 从 JSON 文件或分享 URL 导入会话

Import session data from a JSON file or OpenCode share URL.

opencode import <file>

opencode import session.json
opencode import https://opncd.ai/s/abc123

web

// web 启动带 Web 界面的服务器 // 自动在浏览器中打开

Start a headless OpenCode server with a web interface.

opencode web

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

acp

// acp 启动 Agent Client Protocol 服务器 // 通过 stdin/stdout 使用 nd-JSON 通信

Start an ACP (Agent Client Protocol) server.

opencode acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flag	Description
`--cwd`	Working directory
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

plugin

// plugin 安装插件并更新配置 // 支持全局或项目级安装

Install a plugin and update your config.

opencode plugin <module>
# Or use the alias
opencode plug <module>

Flag	Short	Description
`--global`	`-g`	Install in global config
`--force`	`-f`	Replace existing plugin version

pr

// pr 获取并检出 GitHub PR 分支

Fetch and checkout a GitHub PR branch, then run OpenCode.

opencode pr <number>

db

// db 提供数据库查询工具

Database tools.

opencode db [query]

Flag	Description
`--format`	Output format: `json` or `tsv`

path

// path 显示数据库文件路径

Print the database path.

opencode db path

debug

// debug 提供调试和故障排除工具

Debugging and troubleshooting tools.

opencode debug [command]

uninstall

// uninstall 卸载 OpenCode 并清理相关文件

Uninstall OpenCode and remove all related files.

opencode uninstall

Flag	Short	Description
`--keep-config`	`-c`	Keep configuration files
`--keep-data`	`-d`	Keep session data and snapshots
`--dry-run`	-	Show what would be removed without removing
`--force`	`-f`	Skip confirmation prompts

upgrade

// upgrade 更新 OpenCode 到最新版本或指定版本

Updates opencode to the latest version or a specific version.

opencode upgrade
# Or a specific version
opencode upgrade v0.1.48

Flag	Short	Description
`--method`	`-m`	The installation method that was used; curl, npm, pnpm, bun, brew

Global Flags

// 全局参数适用于所有命令

The opencode CLI takes the following global flags.

Flag	Short	Description
`--help`	`-h`	Display help
`--version`	`-v`	Print version number
`--print-logs`	-	Print logs to stderr
`--log-level`	-	Log level (DEBUG, INFO, WARN, ERROR)
`--pure`	-	Run without external plugins

Environment variables

// 环境变量用于配置 OpenCode 行为 // 可在 .env 文件或 shell 中设置

OpenCode can be configured using environment variables.

Variable	Type	Description
`OPENCODE_AUTO_SHARE`	boolean	Automatically share sessions
`OPENCODE_GIT_BASH_PATH`	string	Path to Git Bash executable on Windows
`OPENCODE_CONFIG`	string	Path to config file
`OPENCODE_TUI_CONFIG`	string	Path to TUI config file
`OPENCODE_CONFIG_DIR`	string	Path to config directory
`OPENCODE_CONFIG_CONTENT`	string	Inline json config content
`OPENCODE_DISABLE_AUTOUPDATE`	boolean	Disable automatic update checks
`OPENCODE_DISABLE_PRUNE`	boolean	Disable pruning of old data
`OPENCODE_DISABLE_TERMINAL_TITLE`	boolean	Disable automatic terminal title updates
`OPENCODE_PERMISSION`	string	Inlined json permissions config
`OPENCODE_DISABLE_DEFAULT_PLUGINS`	boolean	Disable default plugins
`OPENCODE_DISABLE_LSP_DOWNLOAD`	boolean	Disable automatic LSP server downloads
`OPENCODE_ENABLE_EXPERIMENTAL_MODELS`	boolean	Enable experimental models
`OPENCODE_DISABLE_AUTOCOMPACT`	boolean	Disable automatic context compaction
`OPENCODE_DISABLE_CLAUDE_CODE`	boolean	Disable reading from `.claude`
`OPENCODE_DISABLE_CLAUDE_CODE_PROMPT`	boolean	Disable reading `~/.claude/CLAUDE.md`
`OPENCODE_DISABLE_CLAUDE_CODE_SKILLS`	boolean	Disable loading `.claude/skills`
`OPENCODE_DISABLE_MODELS_FETCH`	boolean	Disable fetching models from remote sources
`OPENCODE_DISABLE_MOUSE`	boolean	Disable mouse capture in the TUI
`OPENCODE_FAKE_VCS`	string	Fake VCS provider for testing purposes
`OPENCODE_CLIENT`	string	Client identifier (defaults to `cli`)
`OPENCODE_ENABLE_EXA`	boolean	Enable Exa web search tools
`OPENCODE_SERVER_PASSWORD`	string	Enable basic auth for `serve`/`web`
`OPENCODE_SERVER_USERNAME`	string	Override basic auth username (default `opencode`)
`OPENCODE_MODELS_URL`	string	Custom URL for fetching models configuration

Experimental

// 实验性功能可能随时更改或移除

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
`OPENCODE_EXPERIMENTAL`	boolean	Enable the experimental umbrella flag
`OPENCODE_EXPERIMENTAL_ICON_DISCOVERY`	boolean	Enable icon discovery
`OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	boolean	Disable copy on select in TUI
`OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	number	Default timeout for bash commands in ms
`OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	number	Max output tokens for LLM responses
`OPENCODE_EXPERIMENTAL_FILEWATCHER`	boolean	Enable file watcher for entire dir
`OPENCODE_EXPERIMENTAL_OXFMT`	boolean	Enable oxfmt formatter
`OPENCODE_EXPERIMENTAL_LSP_TOOL`	boolean	Enable experimental LSP tool
`OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER`	boolean	Disable file watcher
`OPENCODE_EXPERIMENTAL_EXA`	boolean	Enable experimental Exa features
`OPENCODE_EXPERIMENTAL_LSP_TY`	boolean	Enable TY LSP for python files
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	boolean	Enable plan mode
`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`	boolean	Enable background subagent tasks
`OPENCODE_EXPERIMENTAL_EVENT_SYSTEM`	boolean	Enable experimental event system
`OPENCODE_EXPERIMENTAL_NATIVE_LLM`	boolean	Enable native LLM request path
`OPENCODE_EXPERIMENTAL_PARALLEL`	boolean	Enable parallel web search execution
`OPENCODE_EXPERIMENTAL_SCOUT`	boolean	Enable Scout subagent
`OPENCODE_EXPERIMENTAL_WORKSPACES`	boolean	Enable workspace support