OpenCode CLILast verified August 26, 2026

OpenCode CLI Cheatsheet

A practical map of OpenCode's complete command surface: documented CLI commands, interactive TUI actions, advanced dev-source features, and dynamic commands supplied by Skills, MCP, project configuration, and plugins.

View the command tree TUI slash commands

opencode — current project

$ opencode

Interactive coding agent ready.

› /models

› /skills

› /review

Type / for this installation's live command list.
Type @ for files. Start with ! for shell mode.

Docs and current dev source are labeled separately.

The essential mental model

OpenCode commands live in four layers

A single help screen cannot show the entire surface. The installed TUI also merges commands discovered from the current project and connected systems.

CLI commands

Stable commands documented for launch, automation, sessions, MCP, providers, servers, and maintenance.

TUI commands

Slash commands and terminal actions available after OpenCode starts.

Dev-source commands

Advanced or newly added commands present on the dev branch but not always documented as stable.

Dynamic commands

Commands assembled at runtime from project config, Skills, MCP prompts, and installed extensions.

Complete overview

OpenCode CLI command tree

The tree combines the documented CLI with commands registered by the current dev entrypoint. Source-only and internal commands can change before a stable release.

opencode command tree

opencode [project]
├── agent
│   ├── create
│   └── list
├── attach [url]
├── providers                      # alias: auth
│   ├── list / ls
│   ├── login [url]
│   └── logout [provider]
├── github
│   ├── install
│   └── run
├── mcp
│   ├── add
│   ├── list / ls
│   ├── auth [name]
│   ├── logout [name]
│   └── debug <name>
├── models [provider]
├── run [message...]
├── serve
├── session
│   ├── list
│   └── delete <sessionID>
├── stats
├── export [sessionID]
├── import <file>
├── web
├── acp
├── uninstall
├── upgrade [target]
├── completion
├── generate                       # advanced
├── pr <number>                    # dev source
├── plugin <module>                # alias: plug
├── db [query]
│   └── path
├── console                        # hidden / internal
│   ├── login [url]
│   ├── logout [email]
│   ├── switch
│   ├── orgs
│   └── open
└── debug
    ├── config       ├── lsp          ├── rg
    ├── file         ├── scrap        ├── skill
    ├── snapshot     ├── startup      ├── agent
    ├── v2           ├── info         ├── paths
    └── wait

Quick start

Commands worth memorizing first

These six cover interactive work, automation, continuation, server reuse, Skills, and MCP diagnostics.

Open the TUI

opencode

Start an interactive OpenCode session in the current directory.

One-shot automation

opencode run "Fix the failing tests"

Run a non-interactive task from a terminal, script, or CI job.

Continue a session

opencode run -c "Continue the implementation"

Continue the most recent session without reopening the full TUI.

Reuse a backend

opencode run --attach http://localhost:4096 "Review this repo"

Attach automation to a running server and avoid repeated startup costs.

Inspect loaded Skills

opencode debug skill

Confirm which Skills OpenCode discovered for the current project.

Debug an MCP server

opencode mcp debug github

Troubleshoot an MCP connection, OAuth flow, or transport problem.

CLI reference

Top-level commands by workflow

Use the badges to distinguish public documentation from capabilities currently visible only in the dev source.

Launch, automation, and servers

Start the TUI, run headless tasks, or separate the OpenCode client from its backend.

opencode [project]

Docs

Start the TUI in the current directory or a project path.

opencode run [message...]

Docs

Run OpenCode non-interactively for scripts, CI, or one-shot tasks.

opencode serve

Docs

Start a headless HTTP server for API access.

opencode attach [url]

Docs

Attach the TUI to an existing OpenCode server.

opencode web

Docs

Start the OpenCode server with its web interface.

opencode acp

Docs

Run the Agent Client Protocol server for editor and client integrations.

Providers, models, and agents

Connect model providers, inspect model identifiers, and manage reusable agents.

opencode providers list

Aliases: auth list, providers ls, auth ls

Dev source

List configured credentials and provider environment variables.

opencode providers login [url]

Aliases: auth login

Dev source

Add provider credentials or authenticate through a provider URL.

opencode providers logout [provider]

Aliases: auth logout

Dev source

Remove stored provider credentials.

opencode models [provider]

Docs

List available models, optionally filtered by provider.

opencode models --refresh

Docs

Refresh the cached catalog from models.dev.

opencode agent create

Docs

Create an agent configuration interactively or with source-supported flags.

opencode agent list

Docs

List the available agents.

MCP and GitHub

Connect external tools and move from issues or pull requests into an agent workflow.

opencode mcp add

Docs

Add an MCP server through the interactive setup.

opencode mcp list

Aliases: mcp ls

Docs

List configured MCP servers and connection state.

opencode mcp auth [name]

Docs

Run OAuth for an MCP server or inspect MCP auth status.

opencode mcp logout [name]

Docs

Remove OAuth credentials for an MCP server.

opencode mcp debug <name>

Docs

Print detailed MCP connection and OAuth diagnostics.

opencode github install

Docs

Install the OpenCode GitHub integration.

opencode github run

Docs

Run the GitHub integration for an event payload.

opencode pr <number>

Dev source

Fetch or check out a GitHub pull request and enter an OpenCode workflow.

Sessions, exports, and usage data

Inspect history, move sessions between installations, and query local OpenCode data.

opencode session list

Docs

List sessions as a table or JSON.

opencode session delete <sessionID>

Docs

Delete a stored session by ID.

opencode export [sessionID]

Docs

Export a session as JSON; prompts for a session when no ID is provided.

opencode import <file>

Docs

Import an exported session file or supported share URL.

opencode stats

Docs

Show token, cost, tool, model, and project usage statistics.

opencode db [query]

Dev source

Open sqlite3 or execute a SQL query against the local OpenCode database.

opencode db path

Dev source

Print the path to the local OpenCode database.

Plugins, maintenance, and generation

Install OpenCode extensions, update the CLI, or use development-oriented generators.

opencode plugin <module>

Aliases: plug <module>

Dev source

Install a plugin package and update local or global configuration.

opencode completion

Dev source

Generate shell completion output.

opencode upgrade [target]

Docs

Upgrade OpenCode, optionally to a selected version.

opencode uninstall

Docs

Remove OpenCode, with options to preserve config or data.

opencode generate

Dev source

Generate the OpenAPI specification for development workflows.

Debug and internal commands

Deep inspection tools for configuration, LSP, file search, Skills, snapshots, and local paths.

opencode debug config

Dev source

Print the final resolved OpenCode configuration.

opencode debug lsp ...

Dev source

Inspect diagnostics, workspace symbols, and document symbols.

opencode debug rg ...

Dev source

Use OpenCode's internal ripgrep-backed file and text search.

opencode debug file ...

Dev source

Search, read, or list files through OpenCode's file layer.

opencode debug skill

Dev source

List Skills discovered by the current OpenCode instance.

opencode debug snapshot ...

Dev source

Track, patch, or diff internal snapshots.

opencode debug startup

Dev source

Inspect startup timing and initialization behavior.

opencode debug info

Dev source

Show version, OS, terminal, and plugin information.

opencode debug paths

Dev source

Print data, config, cache, and state paths.

opencode console ...

Internal

Hidden account and organization console commands; not a stable public API.

Important options

TUI startup and opencode run flags

Startup flags control the interactive client. Run flags are designed for scripts, CI, attached servers, and repeatable automation.

opencode [project] options

--continue, -cDocs

Continue the latest session.

--session, -s <id>Docs

Continue a specific session.

--forkDocs

Fork the continued session; requires --continue or --session.

--prompt <text>Docs

Send an initial prompt when the TUI starts.

--model, -m <provider/model>Docs

Select the starting model.

--agent <name>Docs

Select the starting agent.

--autoDev source

Auto-approve permissions that are not explicitly denied.

--miniDev source

Start the minimal interactive interface.

--no-replayDev source

Disable mini-session history replay.

--replay-limit <number>Dev source

Limit visible replay to the newest N messages in mini mode.

--pureDev source

Run without external plugins.

--port / --hostname / --mdns / --corsDocs

Expose or configure the TUI's backend server transport.

--print-logs / --log-levelDocs

DEBUG | INFO | WARN | ERROR

Print logs and choose their verbosity.

opencode run options

--command <name>Docs

Run a named OpenCode command and pass the message as its arguments.

--continue, -cDocs

Continue the latest session.

--session, -s <id>Docs

Continue a specific session.

--forkDocs

Fork the session being continued.

--shareDocs

Share the created or continued session.

--model, -m <provider/model>Docs

Choose the model for this run.

--agent <name>Docs

Choose the agent for this run.

--file, -f <path>Docs

Attach one or more files to the message.

--format <default|json>Docs

Use formatted output or raw JSON events.

--title [text]Docs

Set a session title, or derive one from the prompt.

--attach <url>Docs

Connect to an already running OpenCode server.

--username, -u / --password, -pDocs

Supply basic-auth credentials for an attached server.

--dir <path>Docs

Set the local working directory or remote directory when attaching.

--variant <name>Docs

Choose a provider-specific model variant or reasoning effort.

--thinkingDocs

Show thinking blocks in command output when available.

--autoDocs

Auto-approve permissions that are not explicitly denied.

--port <number>Docs

Set the local server port instead of using a random one.

Treat --auto as a permission change

It auto-approves permissions that are not explicitly denied. Review project configuration and avoid using it in untrusted repositories unless the surrounding environment provides appropriate isolation.

Interactive TUI

Slash commands and aliases

Type / in the prompt to see the exact list for your installed version, current project, connected MCP servers, and discovered Skills.

Session lifecycle

Create, switch, share, rename, fork, compact, and navigate sessions without leaving the TUI.

/sessions

Aliases: /resume, /continue

Docs

List and switch sessions.

/new

Aliases: /clear

Docs

Start a new session.

/share

Docs

Share the current session or copy its existing share URL.

/unshare

Docs

Disable sharing for the current session.

/rename

Dev source

Rename the current session.

/timeline

Dev source

Jump to a specific message in the session timeline.

/fork

Dev source

Fork the current session from a selected point.

/compact

Aliases: /summarize

Docs

Summarize old context and free context-window space.

/undo

Docs

Undo the latest interaction and its file changes.

/redo

Docs

Restore a previously undone interaction and file changes.

/copy

Dev source

Copy the current session transcript.

/export

Docs

Export the conversation to Markdown through your configured editor.

Display and navigation

Control what the terminal interface shows and how you move through the current conversation.

/timestamps

Aliases: /toggle-timestamps

Dev source

Show or hide message timestamps.

/thinking

Aliases: /toggle-thinking

Docs

Expand or collapse visible thinking blocks; it does not enable reasoning by itself.

/details

Docs

Toggle tool execution details in versions that expose the documented command.

/editor

Docs

Open the configured $EDITOR to compose a longer prompt.

/themes

Docs

Open the theme selector.

/help

Docs

Open TUI help for the installed version.

/exit

Aliases: /quit, /q

Docs

Exit OpenCode.

Models, agents, and integrations

Switch the active model or agent and control connected providers, MCP servers, and Skills.

/models

Aliases: /mo

Dev source

Open the model selector.

/agents

Dev source

Switch the active agent.

/variants

Dev source

Select a model variant when the current model provides variants.

/mcps

Dev source

Toggle MCP servers for the current TUI session.

/connect

Docs

Add or connect a model provider.

/skills

Dev source

Open the Skill selector and insert a selected Skill command.

/status

Dev source

Show current OpenCode status.

/debug

Dev source

Open the TUI debug-information dialog.

Built-in and conditional commands

Prompt commands come from the shared registry; workspace and organization commands appear only when their conditions are met.

/init

Docs

Run guided AGENTS.md setup for the current project.

/review [commit|branch|pr]

Dev source

Review a target, defaulting to uncommitted changes.

/workspaces

Conditional

Manage experimental workspaces.

/warp

Conditional

Change the workspace used by the current session.

/move

Conditional

Move the session to another project directory.

/org

Aliases: /orgs, /switch-org

Conditional

Switch organizations when more than one organization is available.

@src/app.ts

File context

Type @ to fuzzy-search files and add their contents to the conversation.

!npm test

Shell mode

Start the prompt with ! to execute a shell command and add its output to the session.

exit · quit · :q

Direct exit

The current prompt handler also recognizes these direct exit forms without a leading slash.

No fixed command count

The slash-command registry is dynamic

Built-in commands are only the starting point. OpenCode combines project commands, global commands, Skills, and MCP prompts at runtime.

Project or global

Custom commands

Markdown files in .opencode/commands/ or ~/.config/opencode/commands/ become reusable slash commands.

.opencode/commands/test.md
→ /test

Discovered at runtime

Skills

Skills are merged into the command registry when their names do not collide with an existing command.

frontend-design
→ /frontend-design

Server-provided

MCP prompts

Prompts exposed by connected MCP servers can appear as slash commands with positional argument hints.

review_pr
→ /review_pr 123

Installation-dependent

Plugins

Plugins can extend OpenCode behavior and TUI actions, so two installations may not expose the same surface.

opencode plugin <module>

Custom command template features

$ARGUMENTS · $1 · $2

Arguments

Pass the complete argument string or address parsed positional arguments.

!`git log --oneline -10`

Shell interpolation

Run a shell command and inject its output into the command prompt.

@src/auth.ts

File references

Include a project file in the generated prompt context.

Practical combinations

OpenCode workflows that scale

The highest-value patterns combine CLI automation with session continuity, a reusable server, and in-TUI project commands.

Initialize a project

Open the repository and let OpenCode create or update its project instructions.

cd project
opencode
# In the TUI:
/init

Automate a coding task

Choose an agent and run a task without opening the interactive interface.

opencode run --agent build \
  "Implement the feature described in issue.md"

Produce machine-readable events

Use JSON output when another script or CI step needs to consume the run.

opencode run --format json \
  "Review the repository for TypeScript errors"

Reuse a long-running server

Start one backend, then attach runs or another terminal to it.

opencode serve --port 4096
opencode run --attach http://localhost:4096 \
  "Explain the authentication flow"

Diagnose configuration

Inspect resolved config, paths, Skills, and a problematic MCP server.

opencode debug config
opencode debug paths
opencode debug skill
opencode mcp debug <name>

Bypass a broken external plugin

Launch without external plugins to determine whether a plugin causes startup failure.

opencode --pure

The most reliable live command check

OpenCode changes quickly. Use the installed binary and TUI autocomplete as the final authority for your machine.

opencode --help

opencode run --help

opencode debug --help

opencode providers --help

opencode db --help

/help

/

Sources and version notes

Official documentation and current dev source

This page is an English quick reference, not a promise that every dev-source command ships in the latest stable package. Check local --help output before automating source-only features.

CLI documentation TUI documentation Custom commands CLI entrypoint source TUI launcher source Dynamic command registry

Docs and dev can diverge briefly. A Dev source badge means the command was verified in the current source tree but may not exist in an older installed release. Conditional commands depend on feature flags, workspace state, or account state. Internal commands should not be treated as stable automation APIs.