--- title: "CLI commands" description: "Reference for the opencode command line." --- Every command accepts `--help` for its full flag list, for example `opencode run --help`. Some server-backed commands accept `--standalone` to run a private server or `--server ` to target a specific one; check the command's help for its supported flags. ## run Sends a message and prints the reply without opening the interactive interface. ```bash $ opencode run "Explain this repository" ``` ### CI In CI, pass a provider API key as a secret and use standalone mode so the private server receives it. For example, this GitHub Actions job reviews the checked-out repository: ```yaml name: OpenCode review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install --global @opencode/cli - run: opencode run --standalone --model anthropic/claude-sonnet-5-5 "Review this repository for correctness and summarize any issues." env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` Choose a model. ```bash $ opencode run --model anthropic/claude-sonnet-5-5 "Refactor parseToken" ``` Continue the last session. ```bash $ opencode run --continue "Now handle the expired case" ``` Emit newline-delimited JSON for scripts. ```bash $ opencode run --format json "List the TODO comments" ``` Attach files to the message. ```bash $ opencode run --file src/server.ts --file src/client.ts "Review these for bugs" ``` Run with a specific agent. ```bash $ opencode run --agent build "Fix the failing test" ``` Continue a specific session. ```bash $ opencode run --session ses_4f2a1c "Check edge cases" ``` Auto-approve permissions that are not explicitly denied. ```bash $ opencode run --auto "Fix the failing test" ``` Create the session archived so scripted or CI runs stay out of session lists and the inbox. The session still exists: `opencode session list` includes it, and you can open it by ID. ```bash $ opencode run --archived "Review this diff" ``` View all subcommands and flags. ```bash $ opencode run --help ``` ## mini Starts the minimal interactive interface instead of the full-screen TUI. ```bash $ opencode mini ``` Continue the last session. ```bash $ opencode mini --continue ``` Start with a model and an initial prompt. ```bash $ opencode mini --model anthropic/claude-sonnet-5-5 --prompt "Summarize this repository" ``` Continue a specific session. ```bash $ opencode mini --session ses_4f2a1c ``` View all subcommands and flags. ```bash $ opencode mini --help ``` ## session Manages sessions. ```bash $ opencode session list ``` Limit the list and print JSON. ```bash $ opencode session list --max-count 20 --format json ``` Delete a session and its child sessions. ```bash $ opencode session delete ses_9c1b08 ``` Export session data as JSON. ```bash $ opencode session export ses_4f2a1c ``` Redact sensitive transcript and file data when exporting. ```bash $ opencode session export ses_4f2a1c --sanitize ``` Import session data from a JSON file or URL. ```bash $ opencode session import session.json ``` Import into a specific directory. ```bash $ opencode session import session.json --directory ~/code/project ``` View all subcommands and flags. ```bash $ opencode session --help ``` ## auth Manages AI providers and credentials. ```bash $ opencode auth list ``` List them as JSON. ```bash $ opencode auth list --format json ``` Log in to a provider. ```bash $ opencode auth login anthropic ``` Log in with a specific authentication method. ```bash $ opencode auth login anthropic --method key ``` Log out of a saved account. ```bash $ opencode auth logout anthropic work ``` Switch the active account for an integration. ```bash $ opencode auth switch anthropic work ``` Export saved credentials and import them on another machine. The file contains secrets. ```bash $ opencode auth export anthropic > credentials.json $ opencode auth import credentials.json ``` View all subcommands and flags. ```bash $ opencode auth --help ``` ## models Lists every available model. ```bash $ opencode models ``` View all subcommands and flags. ```bash $ opencode models --help ``` ## mcp Manages MCP (Model Context Protocol) servers. ```bash $ opencode mcp list ``` Add a remote server. ```bash $ opencode mcp add context7 --url https://mcp.context7.com/mcp ``` Add a local server to the global config. ```bash $ opencode mcp add everything --global -- npx -y @modelcontextprotocol/server-everything ``` Add a local server with an environment variable. ```bash $ opencode mcp add everything --env LOG_LEVEL=debug -- npx -y @modelcontextprotocol/server-everything ``` Add a remote server with a header. ```bash $ opencode mcp add context7 --url https://mcp.context7.com/mcp --header CONTEXT7_API_KEY=secret ``` Authenticate with an OAuth-capable remote server. ```bash $ opencode mcp auth sentry ``` Remove stored OAuth credentials for a server. ```bash $ opencode mcp logout sentry ``` View all subcommands and flags. ```bash $ opencode mcp --help ``` ## plugin Manages plugins. ```bash $ opencode plugin list ``` Include built-in server plugins. ```bash $ opencode plugin list --builtin ``` Install a plugin and add it to the global configuration. ```bash $ opencode plugin add @example/opencode-tui ``` Check package plugins for updates. ```bash $ opencode plugin check ``` Update package plugins. ```bash $ opencode plugin update ``` Remove a plugin from global configuration. ```bash $ opencode plugin remove @example/opencode-tui ``` View all subcommands and flags. ```bash $ opencode plugin --help ``` ## stats Shows shareable usage statistics. ```bash $ opencode stats ``` Show the last 7 days. ```bash $ opencode stats --days 7 ``` Show model usage. ```bash $ opencode stats --models ``` Show cost and token details. ```bash $ opencode stats --cost ``` Print JSON instead of a report. ```bash $ opencode stats --json ``` Show only the current project. ```bash $ opencode stats --project . ``` View all subcommands and flags. ```bash $ opencode stats --help ``` ## serve Starts the API and web server. See [Web](/cli/web). ```bash $ opencode serve ``` Bind to all interfaces on a fixed port. ```bash $ opencode serve --hostname 0.0.0.0 --port 4096 ``` Allow a browser client from another origin. ```bash $ opencode serve --cors https://app.example.com ``` View all subcommands and flags. ```bash $ opencode serve --help ``` ## pair Prints one-time links, plus a QR code of the first one, that sign a browser or app in to the server. Links expire after 5 minutes and work once. ```bash $ opencode pair ``` Use an external URL in the links. ```bash $ opencode pair --url https://dev.example.com ``` Pair from anywhere through an OpenTunnel remote address. This exposes the server to the internet, so the first time it enables remote access it explains this and asks you to accept. See [Remote access](/cli/web#remote-access). ```bash $ opencode pair --remote ``` Accept without a prompt, for example in a script without a terminal. ```bash $ opencode pair --remote --yes ``` View all subcommands and flags. ```bash $ opencode pair --help ``` ## service Manages the background server. See [Web](/cli/web). ```bash $ opencode service start ``` Restart it. ```bash $ opencode service restart ``` Show its status. ```bash $ opencode service status ``` Stop it. ```bash $ opencode service stop ``` Read a setting. ```bash $ opencode service get hostname ``` Set a setting. ```bash $ opencode service set hostname 0.0.0.0 ``` Allow an extra CORS origin. ```bash $ opencode service set cors https://app.example.com ``` Pass an environment variable to the server process. ```bash $ opencode service set env OPENCODE_LOG_LEVEL DEBUG ``` Reset a setting to its default. ```bash $ opencode service unset hostname ``` View all subcommands and flags. ```bash $ opencode service --help ``` ## reload Reloads configuration without restarting the server. Running sessions continue with fresh services at the next step boundary. ```bash $ opencode reload ``` ## api Makes a request to the running server. ```bash $ opencode api GET /api/session ``` Call an operation ID with a query parameter. ```bash $ opencode api session.list --param limit=10 ``` Send a JSON body. ```bash $ opencode api session.create --data '{"title": "New session"}' ``` Add a request header. ```bash $ opencode api GET /api/session -H "accept: application/json" ``` View all subcommands and flags. ```bash $ opencode api --help ``` ## acp Starts an Agent Client Protocol server over stdin and stdout for editor integrations. It runs until the client closes the connection. ```bash $ opencode acp ``` View all subcommands and flags. ```bash $ opencode acp --help ``` ## debug Provides debugging and troubleshooting tools. ```bash $ opencode debug agents ``` List configuration sources. ```bash $ opencode debug config ``` Write a heap snapshot of the running background server and print its path. ```bash $ opencode debug heap-dump ``` Write the snapshot into a directory of your choice. ```bash $ opencode debug heap-dump --directory ./snapshots ``` Show global paths. ```bash $ opencode debug paths ``` Print a single path. ```bash $ opencode debug paths db ``` View all subcommands and flags. ```bash $ opencode debug --help ``` ## upgrade Upgrades OpenCode to the latest or a specific version. Alias: `update`. ```bash $ opencode upgrade ``` Upgrade to a specific version with a specific package manager. ```bash $ opencode upgrade 2.0.21 --method bun ``` View all subcommands and flags. ```bash $ opencode upgrade --help ``` ## uninstall Stops background services, removes the global cache, and uninstalls OpenCode. Session data, configuration, and state are not removed. ```bash $ opencode uninstall ``` Preview what would be removed. ```bash $ opencode uninstall --dry-run ``` View all subcommands and flags. ```bash $ opencode uninstall --help ```