12 KiB
CLI
OpenCode CLI options and commands.
The OpenCode CLI by default starts the TUI when run without any arguments. Terminal window
opencode
But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically. Terminal window
opencode run "Explain how closures work in JavaScript"
tui
Start the OpenCode terminal user interface. Terminal window
opencode [project]
Flags Flag Short Description --continue -c Continue the last session --session -s Session ID to continue --fork Fork the session when continuing (use with --continue or --session) --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 Commands
The OpenCode CLI also has the following commands. agent
Manage agents for OpenCode. Terminal window
opencode agent [command]
attach
Attach a terminal to an already running OpenCode backend server started via serve or web commands. Terminal window
opencode attach [url]
This allows using the TUI with a remote OpenCode backend. For example: Terminal window
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
Flags Flag Short Description --dir Working directory to start TUI in --session -s Session ID to continue create
Create a new agent with custom configuration. Terminal window
opencode agent create
This command will guide you through creating a new agent with a custom system prompt and tool configuration. list
List all available agents. Terminal window
opencode agent list
auth
Command to manage credentials and login for providers. Terminal window
opencode auth [command]
login
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. Terminal window
opencode auth login
When OpenCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project. list
Lists all the authenticated providers as stored in the credentials file. Terminal window
opencode auth list
Or the short version. Terminal window
opencode auth ls
logout
Logs you out of a provider by clearing it from the credentials file. Terminal window
opencode auth logout
github
Manage the GitHub agent for repository automation. Terminal window
opencode github [command]
install
Install the GitHub agent in your repository. Terminal window
opencode github install
This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more. run
Run the GitHub agent. This is typically used in GitHub Actions. Terminal window
opencode github run
Flags Flag Description --event GitHub mock event to run the agent for --token GitHub personal access token mcp
Manage Model Context Protocol servers. Terminal window
opencode mcp [command]
add
Add an MCP server to your configuration. Terminal window
opencode mcp add
This command will guide you through adding either a local or remote MCP server. list
List all configured MCP servers and their connection status. Terminal window
opencode mcp list
Or use the short version. Terminal window
opencode mcp ls
auth
Authenticate with an OAuth-enabled MCP server. Terminal window
opencode mcp auth [name]
If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.
You can also list OAuth-capable servers and their authentication status. Terminal window
opencode mcp auth list
Or use the short version. Terminal window
opencode mcp auth ls
logout
Remove OAuth credentials for an MCP server. Terminal window
opencode mcp logout [name]
debug
Debug OAuth connection issues for an MCP server. Terminal window
opencode mcp debug
models
List all available models from configured providers. Terminal window
opencode models [provider]
This command displays all models available across your configured providers in the format provider/model.
This is useful for figuring out the exact model name to use in your config.
You can optionally pass a provider ID to filter models by that provider. Terminal window
opencode models anthropic
Flags Flag Description --refresh Refresh the models cache from models.dev --verbose Use more verbose model output (includes metadata like costs)
Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in OpenCode. Terminal window
opencode models --refresh
run
Run opencode in non-interactive mode by passing a prompt directly. Terminal window
opencode run [message..]
This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example. Terminal window
opencode run Explain the use of context in Go
You can also attach to a running opencode serve instance to avoid MCP server cold boot times on every run: Terminal window
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"
Flags 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 (use with --continue or --session) --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 (uses truncated prompt if no value provided) --attach Attach to a running opencode server (e.g., http://localhost:4096) --port Port for the local server (defaults to random port) serve
Start a headless OpenCode server for API access. Check out the server docs for the full HTTP interface. Terminal window
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 (username defaults to opencode). Flags Flag Description --port Port to listen on --hostname Hostname to listen on --mdns Enable mDNS discovery --cors Additional browser origin(s) to allow CORS session
Manage OpenCode sessions. Terminal window
opencode session [command]
list
List all OpenCode sessions. Terminal window
opencode session list
Flags Flag Short Description --max-count -n Limit to N most recent sessions --format Output format: table or json (table) stats
Show token usage and cost statistics for your OpenCode sessions. Terminal window
opencode stats
Flags Flag Description --days Show stats for the last N days (all time) --tools Number of tools to show (all) --models Show model usage breakdown (hidden by default). Pass a number to show top N --project Filter by project (all projects, empty string: current project) export
Export session data as JSON. Terminal window
opencode export [sessionID]
If you don’t provide a session ID, you’ll be prompted to select from available sessions. import
Import session data from a JSON file or OpenCode share URL. Terminal window
opencode import
You can import from a local file or an OpenCode share URL. Terminal window
opencode import session.json opencode import https://opncd.ai/s/abc123
web
Start a headless OpenCode server with a web interface. Terminal window
opencode web
This starts an HTTP server and opens a web browser to access OpenCode through a web interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode). Flags Flag Description --port Port to listen on --hostname Hostname to listen on --mdns Enable mDNS discovery --cors Additional browser origin(s) to allow CORS acp
Start an ACP (Agent Client Protocol) server. Terminal window
opencode acp
This command starts an ACP server that communicates via stdin/stdout using nd-JSON. Flags Flag Description --cwd Working directory --port Port to listen on --hostname Hostname to listen on uninstall
Uninstall OpenCode and remove all related files. Terminal window
opencode uninstall
Flags 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
Updates opencode to the latest version or a specific version. Terminal window
opencode upgrade [target]
To upgrade to the latest version. Terminal window
opencode upgrade
To upgrade to a specific version. Terminal window
opencode upgrade v0.1.48
Flags 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) Environment variables
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_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 (prompt + skills) 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_FAKE_VCS string Fake VCS provider for testing purposes OPENCODE_DISABLE_FILETIME_CHECK boolean Disable file time checking for optimization 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 all experimental features 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 experimental LSP type checking OPENCODE_EXPERIMENTAL_MARKDOWN boolean Enable experimental markdown features OPENCODE_EXPERIMENTAL_PLAN_MODE boolean Enable plan mode