Something went wrong. Try again.
opencode v2 mirror
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733---title: CLIdescription: OpenCode CLI options and commands.---
import { Tabs, TabItem } from "@astrojs/starlight/components"
The OpenCode CLI by default starts the [TUI](/docs/tui) when run without any arguments.
```bashopencode```
But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.
```bashopencode run "Explain how closures work in JavaScript"```
---
### tui
Start the OpenCode terminal user interface.
```bashopencode [project]```
#### Flags
| Flag | Short | Description || ------------------------------------------- | ----- | ----------------------------------------------------------------------- || <nobr><code>{"--continue"}</code></nobr> | `-c` | Continue the last session || <nobr><code>{"--session"}</code></nobr> | `-s` | Session ID to continue || <nobr><code>{"--fork"}</code></nobr> | | Fork the session when continuing (use with `--continue` or `--session`) || <nobr><code>{"--prompt"}</code></nobr> | | Prompt to use || <nobr><code>{"--model"}</code></nobr> | `-m` | Model to use in the form of provider/model || <nobr><code>{"--agent"}</code></nobr> | | Agent to use || <nobr><code>{"--auto"}</code></nobr> | | Auto-approve permissions that are not explicitly denied || <nobr><code>{"--port"}</code></nobr> | | Port to listen on || <nobr><code>{"--hostname"}</code></nobr> | | Hostname to listen on || <nobr><code>{"--mdns"}</code></nobr> | | Enable mDNS discovery || <nobr><code>{"--mdns-domain"}</code></nobr> | | Custom mDNS domain name || <nobr><code>{"--cors"}</code></nobr> | | Additional browser origin(s) to allow CORS |
---
## Commands
The OpenCode CLI also has the following commands.
---
### agent
Manage agents for OpenCode.
```bashopencode agent [command]```
---
#### create
Create a new agent with custom configuration.
```bashopencode 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.
#### Flags
| Flag | Short | Description || ------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || <nobr><code>{"--path"}</code></nobr> | | Directory to write the agent file to (defaults to global or `.opencode/agent` based on the prompt) || <nobr><code>{"--description"}</code></nobr> | | What the agent should do || <nobr><code>{"--mode"}</code></nobr> | | Agent mode: `all`, `primary`, or `subagent` || <nobr><code>{"--permissions"}</code></nobr> | | Comma-separated list of permissions to allow (default: all). Available: `bash`, `read`, `edit`, `glob`, `grep`, `webfetch`, `task`, `websearch`, `lsp`, `skill`. Anything omitted is denied. Alias: `--tools` || <nobr><code>{"--model"}</code></nobr> | `-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.
```bashopencode agent list```
---
### attach
Attach a terminal to an already running OpenCode backend server started via `serve` or `web` commands.
```bashopencode attach [url]```
This allows using the TUI with a remote OpenCode backend. For example:
```bash# Start the backend server for web/mobile accessopencode web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backendopencode attach http://10.20.30.40:4096```
#### Flags
| Flag | Short | Description || ---------------------------------------- | ----- | -------------------------------------------------------------------------- || <nobr><code>{"--dir"}</code></nobr> | | Working directory to start TUI in || <nobr><code>{"--continue"}</code></nobr> | `-c` | Continue the last session || <nobr><code>{"--session"}</code></nobr> | `-s` | Session ID to continue || <nobr><code>{"--fork"}</code></nobr> | | Fork the session when continuing (use with `--continue` or `--session`) || <nobr><code>{"--password"}</code></nobr> | `-p` | Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`) || <nobr><code>{"--username"}</code></nobr> | `-u` | Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`) |
---
### auth
Command to manage credentials and login for providers.
```bashopencode auth [command]```
---
#### login
OpenCode is powered by the provider list at [Models.dev](https://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`.
```bashopencode 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.
##### Flags
| Flag | Short | Description || ---------------------------------------- | ----- | ---------------------------------------------------- || <nobr><code>{"--provider"}</code></nobr> | `-p` | Provider ID or name to log in to || <nobr><code>{"--method"}</code></nobr> | `-m` | Login method label to use, skipping method selection |
---
#### list
Lists all the authenticated providers as stored in the credentials file.
```bashopencode auth list```
Or the short version.
```bashopencode auth ls```
---
#### logout
Logs you out of a provider by clearing it from the credentials file.
```bashopencode auth logout```
---
### github
Manage the GitHub agent for repository automation.
```bashopencode github [command]```
---
#### install
Install the GitHub agent in your repository.
```bashopencode github install```
This sets up the necessary GitHub Actions workflow and guides you through the configuration process. [Learn more](/docs/github).
---
#### run
Run the GitHub agent. This is typically used in GitHub Actions.
```bashopencode github run```
##### Flags
| Flag | Description || ------------------------------------- | -------------------------------------- || <nobr><code>{"--event"}</code></nobr> | GitHub mock event to run the agent for || <nobr><code>{"--token"}</code></nobr> | GitHub personal access token |
---
### mcp
Manage Model Context Protocol servers.
```bashopencode mcp [command]```
---
#### add
Add an MCP server to your configuration.
```bashopencode 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.
```bashopencode mcp list```
Or use the short version.
```bashopencode mcp ls```
---
#### auth
Authenticate with an OAuth-enabled MCP server.
```bashopencode 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.
```bashopencode mcp auth list```
Or use the short version.
```bashopencode mcp auth ls```
---
#### logout
Remove OAuth credentials for an MCP server.
```bashopencode mcp logout [name]```
---
#### debug
Debug OAuth connection issues for an MCP server.
```bashopencode mcp debug <name>```
---
### models
List all available models from configured providers.
```bashopencode 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](/docs/config/).
You can optionally pass a provider ID to filter models by that provider.
```bashopencode models anthropic```
#### Flags
| Flag | Description || --------------------------------------- | ------------------------------------------------------------ || <nobr><code>{"--refresh"}</code></nobr> | Refresh the models cache from models.dev || <nobr><code>{"--verbose"}</code></nobr> | 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.
```bashopencode models --refresh```
---
### run
Run opencode in non-interactive mode by passing a prompt directly.
```bashopencode run [message..]```
This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
```bash "opencode run"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:
```bash# Start a headless server in one terminalopencode serve
# In another terminal, run commands that attach to itopencode run --attach http://localhost:4096 "Explain async/await in JavaScript"```
#### Flags
| Flag | Short | Description || ---------------------------------------- | ----- | -------------------------------------------------------------------------- || <nobr><code>{"--command"}</code></nobr> | | The command to run, use message for args || <nobr><code>{"--continue"}</code></nobr> | `-c` | Continue the last session || <nobr><code>{"--session"}</code></nobr> | `-s` | Session ID to continue || <nobr><code>{"--fork"}</code></nobr> | | Fork the session when continuing (use with `--continue` or `--session`) || <nobr><code>{"--share"}</code></nobr> | | Share the session || <nobr><code>{"--model"}</code></nobr> | `-m` | Model to use in the form of provider/model || <nobr><code>{"--agent"}</code></nobr> | | Agent to use || <nobr><code>{"--file"}</code></nobr> | `-f` | File(s) to attach to message || <nobr><code>{"--format"}</code></nobr> | | Format: default (formatted) or json (raw JSON events) || <nobr><code>{"--title"}</code></nobr> | | Title for the session (uses truncated prompt if no value provided) || <nobr><code>{"--attach"}</code></nobr> | | Attach to a running opencode server (e.g., http://localhost:4096) || <nobr><code>{"--password"}</code></nobr> | `-p` | Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`) || <nobr><code>{"--username"}</code></nobr> | `-u` | Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`) || <nobr><code>{"--dir"}</code></nobr> | | Directory to run in, or path on the remote server when attaching || <nobr><code>{"--port"}</code></nobr> | | Port for the local server (defaults to random port) || <nobr><code>{"--variant"}</code></nobr> | | Model variant (provider-specific reasoning effort) || <nobr><code>{"--thinking"}</code></nobr> | | Show thinking blocks || <nobr><code>{"--auto"}</code></nobr> | | Auto-approve permissions that are not explicitly denied |
---
### serve
Start a headless OpenCode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
```bashopencode 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 || ------------------------------------------- | ------------------------------------------ || <nobr><code>{"--port"}</code></nobr> | Port to listen on || <nobr><code>{"--hostname"}</code></nobr> | Hostname to listen on || <nobr><code>{"--mdns"}</code></nobr> | Enable mDNS discovery || <nobr><code>{"--mdns-domain"}</code></nobr> | Custom mDNS domain name || <nobr><code>{"--cors"}</code></nobr> | Additional browser origin(s) to allow CORS |
---
### session
Manage OpenCode sessions.
```bashopencode session [command]```
---
#### list
List all OpenCode sessions.
```bashopencode session list```
##### Flags
| Flag | Short | Description || ----------------------------------------- | ----- | ------------------------------------ || <nobr><code>{"--max-count"}</code></nobr> | `-n` | Limit to N most recent sessions || <nobr><code>{"--format"}</code></nobr> | | Output format: table or json (table) |
---
#### delete
Delete an OpenCode session.
```bashopencode session delete <sessionID>```
---
### stats
Show token usage and cost statistics for your OpenCode sessions.
```bashopencode stats```
#### Flags
| Flag | Description || --------------------------------------- | --------------------------------------------------------------------------- || <nobr><code>{"--days"}</code></nobr> | Show stats for the last N days (all time) || <nobr><code>{"--tools"}</code></nobr> | Number of tools to show (all) || <nobr><code>{"--models"}</code></nobr> | Show model usage breakdown (hidden by default). Pass a number to show top N || <nobr><code>{"--project"}</code></nobr> | Filter by project (all projects, empty string: current project) |
---
### export
Export session data as JSON.
```bashopencode export [sessionID]```
If you don't provide a session ID, you'll be prompted to select from available sessions.
#### Flags
| Flag | Description || ---------------------------------------- | ------------------------------------- || <nobr><code>{"--sanitize"}</code></nobr> | Redact sensitive transcript/file data |
---
### import
Import session data from a JSON file or OpenCode share URL.
```bashopencode import <file>```
You can import from a local file or an OpenCode share URL.
```bashopencode import session.jsonopencode import https://opncd.ai/s/abc123```
---
### web
Start a headless OpenCode server with a web interface.
```bashopencode 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 || ------------------------------------------- | ------------------------------------------ || <nobr><code>{"--port"}</code></nobr> | Port to listen on || <nobr><code>{"--hostname"}</code></nobr> | Hostname to listen on || <nobr><code>{"--mdns"}</code></nobr> | Enable mDNS discovery || <nobr><code>{"--mdns-domain"}</code></nobr> | Custom mDNS domain name || <nobr><code>{"--cors"}</code></nobr> | Additional browser origin(s) to allow CORS |
---
### acp
Start an ACP (Agent Client Protocol) server.
```bashopencode acp```
This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
#### Flags
| Flag | Description || ------------------------------------------- | ------------------------------------------ || <nobr><code>{"--cwd"}</code></nobr> | Working directory || <nobr><code>{"--port"}</code></nobr> | Port to listen on || <nobr><code>{"--hostname"}</code></nobr> | Hostname to listen on || <nobr><code>{"--mdns"}</code></nobr> | Enable mDNS discovery || <nobr><code>{"--mdns-domain"}</code></nobr> | Custom mDNS domain name || <nobr><code>{"--cors"}</code></nobr> | Additional browser origin(s) to allow CORS |
---
### plugin
Install a plugin and update your config.
```bashopencode plugin <module>```
Or use the alias.
```bashopencode plug <module>```
#### Flags
| Flag | Short | Description || -------------------------------------- | ----- | ------------------------------- || <nobr><code>{"--global"}</code></nobr> | `-g` | Install in global config || <nobr><code>{"--force"}</code></nobr> | `-f` | Replace existing plugin version |
---
### pr
Fetch and checkout a GitHub PR branch, then run OpenCode.
```bashopencode pr <number>```
---
### db
Database tools.
```bashopencode db [query]```
#### Flags
| Flag | Description || -------------------------------------- | ------------------------------ || <nobr><code>{"--format"}</code></nobr> | Output format: `json` or `tsv` |
---
#### path
Print the database path.
```bashopencode db path```
---
### debug
Debugging and troubleshooting tools.
```bashopencode debug [command]```
---
### uninstall
Uninstall OpenCode and remove all related files.
```bashopencode uninstall```
#### Flags
| Flag | Short | Description || ------------------------------------------- | ----- | ------------------------------------------- || <nobr><code>{"--keep-config"}</code></nobr> | `-c` | Keep configuration files || <nobr><code>{"--keep-data"}</code></nobr> | `-d` | Keep session data and snapshots || <nobr><code>{"--dry-run"}</code></nobr> | | Show what would be removed without removing || <nobr><code>{"--force"}</code></nobr> | `-f` | Skip confirmation prompts |
---
### upgrade
Updates opencode to the latest version or a specific version.
```bashopencode upgrade [target]```
To upgrade to the latest version.
```bashopencode upgrade```
To upgrade to a specific version.
```bashopencode upgrade v0.1.48```
#### Flags
| Flag | Short | Description || -------------------------------------- | ----- | ----------------------------------------------------------------- || <nobr><code>{"--method"}</code></nobr> | `-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 || ------------------------------------------ | ----- | ------------------------------------ || <nobr><code>{"--help"}</code></nobr> | `-h` | Display help || <nobr><code>{"--version"}</code></nobr> | `-v` | Print version number || <nobr><code>{"--print-logs"}</code></nobr> | | Print logs to stderr || <nobr><code>{"--log-level"}</code></nobr> | | Log level (DEBUG, INFO, WARN, ERROR) || <nobr><code>{"--pure"}</code></nobr> | | 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_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 |