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

opencoderun"Explain how closures work in JavaScript"

tui

Start the OpenCode terminal user interface.

Terminal window

opencode [project]

Flags

Flag	Short	Description
`-c`	Continue the last session
`-s`	Session ID to continue
Fork the session when continuing (use with `--continue` or `--session`)
Prompt to use
`-m`	Model to use in the form of provider/model
Agent to use
Port to listen on
Hostname to listen on
Enable mDNS discovery
Custom mDNS domain name
Additional browser origin(s) to allow CORS

Commands

The OpenCode CLI also has the following commands.

agent

Manage agents for OpenCode.

Terminal window

opencodeagent [command]

create

Create a new agent with custom configuration.

Terminal window

opencodeagentcreate

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.

Flags

Flag	Short	Description
Directory to write the agent file to (defaults to global or `.opencode/agent` based on the prompt)
What the agent should do
Agent mode: `all`, `primary`, or `subagent`
Comma-separated list of permissions to allow (default: all). Available: `bash`, `read`, `edit`, `glob`, `grep`, `webfetch`, `task`, `todowrite`, `websearch`, `lsp`, `skill`. Anything omitted is denied. Alias: `--tools`
`-m`	Model to use, in `provider/model` format

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.

list

List all available agents.

Terminal window

opencodeagentlist

attach

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

Terminal window

opencodeattach [url]

This allows using the TUI with a remote OpenCode backend. For example:

Terminal window

# Start the backend server for web/mobile access
opencodeweb--port4096--hostname0.0.0.0
# In another terminal, attach the TUI to the running backend
opencodeattachhttp://10.20.30.40:4096

Flags

Flag	Short	Description
Working directory to start TUI in
`-c`	Continue the last session
`-s`	Session ID to continue
Fork the session when continuing (use with `--continue` or `--session`)
`-p`	Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`)
`-u`	Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`)

auth

Command to manage credentials and login for providers.

Terminal window

opencodeauth [command]

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

opencodeauthlogin

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.

Flags

Flag	Short	Description
`-p`	Provider ID or name to log in to
`-m`	Login method label to use, skipping method selection

list

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

Terminal window

opencodeauthlist

Or the short version.

Terminal window

opencodeauthls

logout

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

Terminal window

opencodeauthlogout

github

Manage the GitHub agent for repository automation.

Terminal window

opencodegithub [command]

install

Install the GitHub agent in your repository.

Terminal window

opencodegithubinstall

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

opencodegithubrun

Flags

Flag	Description
GitHub mock event to run the agent for
GitHub personal access token

mcp

Manage Model Context Protocol servers.

Terminal window

opencodemcp [command]

add

Add an MCP server to your configuration.

Terminal window

opencodemcpadd

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

opencodemcplist

Or use the short version.

Terminal window

opencodemcpls

auth

Authenticate with an OAuth-enabled MCP server.

Terminal window

opencodemcpauth [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

opencodemcpauthlist

Or use the short version.

Terminal window

opencodemcpauthls

logout

Remove OAuth credentials for an MCP server.

Terminal window

opencodemcplogout [name]

debug

Debug OAuth connection issues for an MCP server.

Terminal window

opencodemcpdebug<name>

models

List all available models from configured providers.

Terminal window

opencodemodels [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

opencodemodelsanthropic

Flags

Flag	Description
Refresh the models cache from models.dev
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

opencodemodels--refresh

run

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

Terminal window

opencoderun [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

Terminal window

opencoderunExplaintheuseofcontextinGo

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
opencodeserve
# In another terminal, run commands that attach to it
opencoderun--attachhttp://localhost:4096"Explain async/await in JavaScript"

Flags

Flag	Short	Description
The command to run, use message for args
`-c`	Continue the last session
`-s`	Session ID to continue
Fork the session when continuing (use with `--continue` or `--session`)
Share the session
`-m`	Model to use in the form of provider/model
Agent to use
`-f`	File(s) to attach to message
Format: default (formatted) or json (raw JSON events)
Title for the session (uses truncated prompt if no value provided)
Attach to a running opencode server (e.g., http://localhost:4096)
`-p`	Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`)
`-u`	Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`)
Directory to run in, or path on the remote server when attaching
Port for the local server (defaults to random port)
Model variant (provider-specific reasoning effort)
Show thinking blocks
Auto-approve permissions that are not explicitly denied (dangerous!)

serve

Start a headless OpenCode server for API access. Check out the server docs for the full HTTP interface.

Terminal window

opencodeserve

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 to listen on
Hostname to listen on
Enable mDNS discovery
Custom mDNS domain name
Additional browser origin(s) to allow CORS

session

Manage OpenCode sessions.

Terminal window

opencodesession [command]

list

List all OpenCode sessions.

Terminal window

opencodesessionlist

Flags

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

delete

Delete an OpenCode session.

Terminal window

opencodesessiondelete<sessionID>

stats

Show token usage and cost statistics for your OpenCode sessions.

Terminal window

opencodestats

Flags

Flag	Description
Show stats for the last N days (all time)
Number of tools to show (all)
Show model usage breakdown (hidden by default). Pass a number to show top N
Filter by project (all projects, empty string: current project)

export

Export session data as JSON.

Terminal window

opencodeexport [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

Flags

Flag	Description
Redact sensitive transcript/file data

import

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

Terminal window

opencodeimport<file>

You can import from a local file or an OpenCode share URL.

Terminal window

opencodeimportsession.json
opencodeimporthttps://opncd.ai/s/abc123

web

Start a headless OpenCode server with a web interface.

Terminal window

opencodeweb

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 to listen on
Hostname to listen on
Enable mDNS discovery
Custom mDNS domain name
Additional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

Terminal window

opencodeacp

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

Flags

Flag	Description
Working directory
Port to listen on
Hostname to listen on
Enable mDNS discovery
Custom mDNS domain name
Additional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

Terminal window

opencodeplugin<module>

Or use the alias.

Terminal window

opencodeplug<module>

Flags

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

pr

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

Terminal window

opencodepr<number>

db

Database tools.

Terminal window

opencodedb [query]

Flags

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

path

Print the database path.

Terminal window

opencodedbpath

debug

Debugging and troubleshooting tools.

Terminal window

opencodedebug [command]

uninstall

Uninstall OpenCode and remove all related files.

Terminal window

opencodeuninstall

Flags

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

upgrade

Updates opencode to the latest version or a specific version.

Terminal window

opencodeupgrade [target]

To upgrade to the latest version.

Terminal window

opencodeupgrade

To upgrade to a specific version.

Terminal window

opencodeupgradev0.1.48

Flags

Flag	Short	Description
`-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
`-h`	Display help
`-v`	Print version number
Print logs to stderr
Log level (DEBUG, INFO, WARN, ERROR)
Run without external plugins

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_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` (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_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

URL: https://opencode.ai/docs/cli

CLI