# CLI > These are the docs for OpenCode V1. The latest docs, for OpenCode V2, are at https://opencode.ai/docs/llms.txt. The OpenCode CLI by default starts the [TUI](/docs/tui) when run without any arguments. ```bash opencode ``` But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically. ```bash opencode run "Explain how closures work in JavaScript" ``` --- ### tui Start the OpenCode terminal user interface. ```bash 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 | | {"--auto"} | | Auto-approve permissions that are not explicitly denied | | {"--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 | --- ## Commands The OpenCode CLI also has the following commands. --- ### agent Manage agents for OpenCode. ```bash opencode agent [command] ``` --- #### create Create a new agent with custom configuration. ```bash 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. ##### Flags | Flag | Short | Description | | ------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | {"--path"} | | Config directory whose `agents/` subdirectory receives the file (defaults to global or `.opencode` based on the prompt) | | {"--description"} | | What the agent should do | | {"--mode"} | | Agent mode: `all`, `primary`, or `subagent` | | {"--permissions"} | | 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` | | {"--model"} | `-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. ```bash opencode agent list ``` --- ### attach Attach a terminal to an already running OpenCode backend server started via `serve` or `web` commands. ```bash opencode attach [url] ``` This allows using the TUI with a remote OpenCode backend. For example: ```bash # 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 | | {"--continue"} | `-c` | Continue the last session | | {"--session"} | `-s` | Session ID to continue | | {"--fork"} | | Fork the session when continuing (use with `--continue` or `--session`) | | {"--password"} | `-p` | Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`) | | {"--username"} | `-u` | Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`) | --- ### auth Command to manage credentials and login for providers. ```bash opencode 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`. ```bash 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. ##### Flags | Flag | Short | Description | | ---------------------------------------- | ----- | ---------------------------------------------------- | | {"--provider"} | `-p` | Provider ID or name to log in to | | {"--method"} | `-m` | Login method label to use, skipping method selection | --- #### list Lists all the authenticated providers as stored in the credentials file. ```bash opencode auth list ``` Or the short version. ```bash opencode auth ls ``` --- #### logout Logs you out of a provider by clearing it from the credentials file. ```bash opencode auth logout ``` --- ### completion Generate a shell completion script. ```bash opencode completion ``` --- ### github Manage the GitHub agent for repository automation. ```bash opencode github [command] ``` --- #### install Install the GitHub agent in your repository. ```bash opencode 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. ```bash 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. ```bash opencode mcp [command] ``` --- #### add Add an MCP server to your configuration. ```bash 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. ```bash opencode mcp list ``` Or use the short version. ```bash opencode mcp ls ``` --- #### auth Authenticate with an OAuth-enabled MCP server. ```bash 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. ```bash opencode mcp auth list ``` Or use the short version. ```bash opencode mcp auth ls ``` --- #### logout Remove OAuth credentials for an MCP server. ```bash opencode mcp logout [name] ``` --- #### debug Debug OAuth connection issues for an MCP server. ```bash opencode mcp debug ``` --- ### models List all available models from configured providers. ```bash 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](/docs/config/). You can optionally pass a provider ID to filter models by that provider. ```bash 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. ```bash opencode models --refresh ``` --- ### run Run opencode in non-interactive mode by passing a prompt directly. ```bash opencode 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 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`) | | {"--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) | | {"--password"} | `-p` | Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`) | | {"--username"} | `-u` | Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`) | | {"--dir"} | | Directory to run in, or path on the remote server when attaching | | {"--port"} | | Port for the local server (defaults to random port) | | {"--variant"} | | Model variant (provider-specific reasoning effort) | | {"--thinking"} | | Show thinking blocks | | {"--auto"} | | 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. ```bash 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 | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### session Manage OpenCode sessions. ```bash opencode session [command] ``` --- #### list List all OpenCode sessions. ```bash opencode session list ``` ##### Flags | Flag | Short | Description | | ----------------------------------------- | ----- | ------------------------------------ | | {"--max-count"} | `-n` | Limit to N most recent sessions | | {"--format"} | | Output format: table or json (table) | --- #### delete Delete an OpenCode session. ```bash opencode session delete ``` --- ### stats Show token usage and cost statistics for your OpenCode sessions. ```bash 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. ```bash opencode export [sessionID] ``` If you don't provide a session ID, you'll be prompted to select from available sessions. #### Flags | Flag | Description | | ---------------------------------------- | ------------------------------------- | | {"--sanitize"} | Redact sensitive transcript/file data | --- ### import Import session data from a JSON file. ```bash opencode import ``` ```bash opencode import session.json ``` --- ### web Start a headless OpenCode server with a web interface. ```bash 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 | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### acp Start an ACP (Agent Client Protocol) server. ```bash 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 | | {"--mdns"} | Enable mDNS discovery | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### plugin Install a plugin and update your config. ```bash opencode plugin ``` Or use the alias. ```bash opencode plug ``` #### Flags | Flag | Short | Description | | -------------------------------------- | ----- | ------------------------------- | | {"--global"} | `-g` | Install in global config | | {"--force"} | `-f` | Replace existing plugin version | --- ### pr Fetch and checkout a GitHub PR branch, then run OpenCode. ```bash opencode pr ``` --- ### db Database tools. ```bash opencode db [query] ``` #### Flags | Flag | Description | | -------------------------------------- | ------------------------------ | | {"--format"} | Output format: `json` or `tsv` | --- #### path Print the database path. ```bash opencode db path ``` --- ### debug Debugging and troubleshooting tools. ```bash opencode debug [command] ``` --- #### agent Show a loaded agent's configuration. Use `opencode agent list` to list all agents. ```bash opencode debug agent build ``` --- #### config Show the resolved configuration. ```bash opencode debug config ``` --- #### paths Show global paths (data, config, cache, state). ```bash opencode debug paths ``` This prints all global paths. To print the database path, use: ```bash opencode db path ``` --- #### Other debug commands | Command | Description | | ------------------------------------------- | -------------------------------------------------------- | | `opencode debug info` | Show the version, OS, terminal, and configured plugins | | `opencode debug skill` | List available skills | | `opencode debug scrap` | List known projects | | `opencode debug file list ` | List files in a directory | | `opencode debug file read ` | Read a file as JSON with base64-encoded content | | `opencode debug file search ` | Search file paths | | `opencode debug rg files` | List files using ripgrep; accepts `--glob` and `--limit` | | `opencode debug rg search ` | Search file contents; accepts `--glob` and `--limit` | | `opencode debug lsp diagnostics ` | Get LSP diagnostics for a file | | `opencode debug lsp symbols ` | Search workspace symbols | | `opencode debug lsp document-symbols ` | Get symbols from a document | | `opencode debug snapshot track` | Track the current snapshot state | | `opencode debug snapshot patch ` | Show changed files for a snapshot hash | | `opencode debug snapshot diff ` | Show the diff for a snapshot hash | | `opencode debug startup` | Print startup timing | --- ### uninstall Uninstall OpenCode and remove all related files. ```bash 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. ```bash opencode upgrade [target] ``` To upgrade to the latest version. ```bash opencode upgrade ``` To upgrade to a specific version. ```bash opencode upgrade v0.1.48 ``` To upgrade to OpenCode 2 and remove OpenCode 1: ```bash opencode upgrade --major ``` #### Flags | Flag | Short | Description | | -------------------------------------- | ----- | ----------------------------------------------------------------- | | {"--method"} | `-m` | The installation method that was used; curl, npm, pnpm, bun, brew | | {"--major"} | | Upgrade to OpenCode 2 and remove OpenCode 1 | --- ## 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 can be configured using environment variables. | Variable | Type | Description | | ------------------------------------- | ------- | ---------------------------------------------------------------------------- | | `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_ENABLE_PARALLEL` | boolean | Enable Parallel 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 | | `OPENCODE_MODELS_PATH` | string | Load the model catalog from a local JSON file | | `OPENCODE_DB` | string | Database path; relative paths resolve under the data directory | | `OPENCODE_PURE` | boolean | Run without external plugins, like `--pure` | | `OPENCODE_DISABLE_PROJECT_CONFIG` | boolean | Disable project configuration and project instruction files | | `OPENCODE_DISABLE_EXTERNAL_SKILLS` | boolean | Disable skill discovery in `.claude` and `.agents` directories | | `OPENCODE_DISABLE_EMBEDDED_WEB_UI` | boolean | Disable the bundled web UI and use the remote UI fallback | | `OPENCODE_DISABLE_FFF` | boolean | Use ripgrep instead of the native file finder; enabled by default on Windows | | `OPENCODE_ENABLE_QUESTION_TOOL` | boolean | Enable the question tool for clients other than the CLI, app, and desktop | | `OPENCODE_ALWAYS_NOTIFY_UPDATE` | boolean | Show update notifications even without a newer version | | `OPENCODE_SHOW_TTFD` | boolean | Show time-to-first-delta timing | | `OPENCODE_LOG_LEVEL` | string | Log level: `DEBUG`, `INFO`, `WARN`, or `ERROR` | | `OPENCODE_PRINT_LOGS` | string | Set to `1` to also print logs to stderr | | `OPENCODE_AUTO_HEAP_SNAPSHOT` | boolean | Capture a heap snapshot when memory usage exceeds 2 GiB | --- ### 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_CODE_MODE` | boolean | Enable code-mode tool execution | | `OPENCODE_EXPERIMENTAL_WEBSOCKETS` | boolean | Use WebSockets for OpenAI requests | | `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_WORKSPACES` | boolean | Enable workspace support |