The OpenCode CLI by default starts the TUI when run without any arguments.

But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.

opencode run "Explain how closures work in JavaScript"

tui

Start the OpenCode terminal user interface.

Flags

Commands

The OpenCode CLI also has the following commands.

agent

Manage agents for OpenCode.

attach

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

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

# 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

create

Create a new agent with custom configuration.

This command will guide you through creating a new agent with a custom system prompt and tool configuration.

list

List all available agents.

auth

Command to manage credentials and login for providers.

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.

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.

Or the short version.

logout

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

github

Manage the GitHub agent for repository automation.

opencode github [command]

install

Install the GitHub agent in your repository.

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.

Flags

mcp

Manage Model Context Protocol servers.

add

Add an MCP server to your configuration.

This command will guide you through adding either a local or remote MCP server.

list

List all configured MCP servers and their connection status.

Or use the short version.

auth

Authenticate with an OAuth-enabled MCP server.

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.

Or use the short version.

logout

Remove OAuth credentials for an MCP server.

opencode mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

opencode mcp debug <name>

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.

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.

opencode models anthropic

Flags

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.

opencode models --refresh

run

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

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

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:

# 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

serve

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

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

session

Manage OpenCode sessions.

opencode session [command]

list

List all OpenCode sessions.

Flags

stats

Show token usage and cost statistics for your OpenCode sessions.

Flags

export

Export session data as JSON.

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.

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

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

web

Start a headless OpenCode server with a web interface.

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

acp

Start an ACP (Agent Client Protocol) server.

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

Flags

uninstall

Uninstall OpenCode and remove all related files.

Flags

upgrade

Updates opencode to the latest version or a specific version.

opencode upgrade [target]

To upgrade to the latest version.

To upgrade to a specific version.

Flags

Global Flags

The opencode CLI takes the following global flags.

Environment variables

OpenCode can be configured using environment variables.

Experimental

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