OpenCode CLI Cheat Sheet

opencode

Open the interactive TUI in the current directory

opencode /path/to/project

Open the TUI for a specific project

opencode --prompt "..."

Start TUI with an initial prompt

opencode --continue / opencode -c

Continue the last session

opencode --session <id> / opencode -s <id>

Continue a specific session

opencode --fork --continue

Fork while continuing a previous session

opencode run "prompt"

Run once without the full TUI

opencode auth login

Add provider credentials

opencode models

List configured provider models

opencode upgrade

Upgrade OpenCode

/init

Create/update project AGENTS.md

@

Fuzzy search files and attach selected file content

@alias / @alias/

Add configured reference roots or autocomplete under them

!cmd

Run shell command and add output as tool result

/help

Show available commands

/connect

Add/authenticate an LLM provider

/models

Select/list models

/thinking

Toggle display of model reasoning blocks

/details

Toggle tool execution details

/editor

Compose prompt in $EDITOR

/export

Export current conversation to Markdown

/exit, /quit, /q

Exit

/init

Generate or update AGENTS.md project rules

/new / /clear

Start a new session

/sessions / /resume / /continue

List and switch sessions

/compact / /summarize

Compact current context

/undo

Undo last message and file changes; requires Git

/redo

Redo an undone message; requires Git

/share / /unshare

Share or unshare current session

/themes

Select/list themes

Ctrl+X

Default leader key

Ctrl+X c

Compact session

Ctrl+X e

Open editor

Ctrl+X q

Exit

Ctrl+X x

Export session

Ctrl+X m

Model list

Ctrl+X n

New session

Ctrl+X l

Session list

Ctrl+X t

Theme list

Ctrl+X u / Ctrl+X r

Undo / redo

Tab / Shift+Tab

Cycle primary agents

Ctrl+T

Cycle model variants

Ctrl+X Down

Enter first child subagent session

Right / Left / Up

Next child / previous child / parent session

Shift+Enter, Ctrl+Enter, Alt+Enter, Ctrl+J

Newline in prompt

opencode agent create / agent list

Create or list agents

opencode attach [url]

Attach TUI to running serve/web backend

opencode auth login/list/logout

Manage provider credentials

opencode github install/run

Install or run GitHub agent automation

opencode mcp add/list/auth/logout/debug

Manage MCP servers and OAuth

opencode models [provider]

List models; optional provider filter

opencode serve

Start headless HTTP server

opencode web

Start server with web UI

opencode session list/delete

Manage sessions

opencode stats

Show token and cost stats

opencode export [sessionID]

Export session JSON

opencode import <file-or-url>

Import session JSON or share URL

opencode acp

Start Agent Client Protocol server

opencode plugin <module> / plug <module>

Install plugin and update config

opencode pr <number>

Fetch/check out GitHub PR and run OpenCode

opencode db [query] / db path

Query DB or print DB path

opencode debug

Debugging tools

opencode uninstall

Remove OpenCode files

--help, -h / --version, -v

Help / version

--print-logs, --log-level DEBUG/INFO/WARN/ERROR

Log output and level

--pure

Run without external plugins

--model provider/model, -m

Choose model

--agent <name>

Choose agent

--continue, -c / --session <id>, -s

Continue last/specific session

--fork

Fork continued session

--port, --hostname, --cors, --mdns, --mdns-domain

Server/TUI networking

opencode run "prompt"

Non-interactive single run

opencode run --command <cmd> ...

Run a configured command; message becomes args

--file path, -f path

Attach files to message

--format json

Emit raw JSON events

--share

Share resulting session

--title "..."

Set session title

--attach http://localhost:4096 "..."

Reuse running opencode serve backend

--variant <name>

Use model variant

--thinking

Show thinking blocks

--dangerously-skip-permissions

Auto-approve anything not explicitly denied ⚠️

~/.config/opencode/opencode.json

Global runtime config

~/.config/opencode/tui.json

Global TUI config

opencode.json / opencode.jsonc

Project runtime config

tui.json / tui.jsonc

Project TUI config

.opencode/agents/, commands/, plugins/, skills/, tools/, themes/

Project extensions

.well-known/opencode

Remote organization defaults

OPENCODE_CONFIG / OPENCODE_CONFIG_DIR

Custom config file/dir

OPENCODE_CONFIG_CONTENT

Inline JSON override

/etc/opencode/, /Library/Application Support/opencode/, %ProgramData%\opencode

Managed config

$schema

https://opencode.ai/config.json or https://opencode.ai/tui.json

model, small_model

Main model and cheaper small-task model

provider

Provider definitions/options

default_agent, agent

Default and custom agents

command

Custom slash commands

permission

Tool/action policy

mcp, plugin, instructions

MCP servers, plugins, extra rule files/globs/URLs

share

manual, auto, or disabled

snapshot

Enable/disable undo snapshots

autoupdate

true, false, or "notify"

formatter, lsp

Enable/configure formatters and LSP

compaction.auto/prune/reserved

Context compaction behavior

watcher.ignore

File watcher ignore globs

enabled_providers, disabled_providers

Provider allow/deny lists

theme

UI theme

keybinds

Shortcut overrides

leader_timeout

Default 2000 ms

scroll_speed, scroll_acceleration.enabled

Scroll behavior

diff_style

"auto" or "stacked"

mouse

Capture mouse; set false for native terminal selection

read

File reads; .env and .env.* denied by default

edit

edit, write, apply_patch

bash

Shell commands

glob, grep

File and content search

task

Subagent launches

skill

Skill loading

lsp

LSP queries

todowrite

Todo tracking

webfetch, websearch

URL fetch and web search

question

Ask user questions during execution

external_directory

Paths outside project; asks by default

doom_loop

Repeated identical tool calls; asks by default

"permission": "allow"

Allow all except safety defaults

"permission": { "*": "ask" }

Ask by default

"edit": "deny"

Block file changes

"bash": { "*": "ask", "git *": "allow", "rm *": "deny" }

Granular shell policy

"external_directory": { "~/work/**": "allow" }

Allow outside project path

agent.<name>.permission

Agent-specific override

permission.<mcp>_*

Control all tools from an MCP server

bash, read, edit, write, apply_patch

Command/file operations

grep, glob

Search via ripgrep; respects .gitignore

lsp

Experimental definitions/references/hover/symbols/calls

skill, todowrite, question

Skill loading, task tracking, user prompts

webfetch, websearch

URL retrieval and Exa search

build

Primary

Default development agent

plan

Primary

Planning/review; edits and bash ask by default

general

Subagent

General multi-step or parallel work

explore

Subagent

Fast read-only codebase exploration

scout

Subagent

Read-only external docs/dependency research

compaction, title, summary

Hidden primary

Automatic system agents

Switch primary agent

Tab / Shift+Tab

Invoke subagent

@explore find auth middleware

Create/list agents

opencode agent create / opencode agent list

Define agents

agent in config, .opencode/agents/<name>.md, or ~/.config/opencode/agents/<name>.md

Set default

"default_agent": "build" or "plan"

Control subagent calls

permission.task patterns

description

Required usage hint

mode

primary, subagent, or all; default all

model, prompt, permission

Agent model, system prompt, and policy

steps

Max agentic iterations

temperature, top_p

Randomness/diversity

disable, hidden, color

Availability and UI

Extra keys

Provider-specific options, e.g. reasoningEffort

.opencode/skills/<name>/SKILL.md

Project OpenCode skill

~/.config/opencode/skills/<name>/SKILL.md

Global OpenCode skill

.claude/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md

Claude-compatible skills

.agents/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md

Agent-compatible skills

opencode mcp add

Add local or remote server

opencode mcp list / ls

List servers/status

opencode mcp auth [name]

OAuth login

opencode mcp auth list

OAuth status

opencode mcp logout [name]

Remove OAuth credentials

opencode mcp debug <name>

Debug connection/OAuth

mcp.<name>.enabled = false

Disable without deleting

Local

type: "local", command: [...]

environment, enabled, timeout

Remote

type: "remote", url

headers, oauth, enabled, timeout

OAuth

Remote server with optional oauth

clientId, clientSecret, scope; oauth: false disables auto-OAuth

Add provider

/connect or opencode auth login

Credential file

~/.local/share/opencode/auth.json

List auth/models

opencode auth list, opencode models [provider]

Refresh models

opencode models --refresh

Verbose metadata

opencode models --verbose

Select in TUI

/models

Set default

"model": "provider/model"

Override run

--model provider/model

Cycle variants

Ctrl+T

Restrict providers

enabled_providers / disabled_providers

provider.<id>.options.baseURL

Proxy/custom endpoint

options.timeout, options.chunkTimeout

Request/stream timeouts

models.<model>.options

Model-specific options

models.<model>.variants.<name>

Named reasoning/provider variants

variants.<name>.disabled

Hide variant

Project/global file

.opencode/commands/<name>.md or ~/.config/opencode/commands/<name>.md

Config command

command.<name> in config

Arguments

$ARGUMENTS, $1, $2, ...

Shell output

command in template

File context

@path/to/file in template

Overrides

description, agent, model, subtask

AGENTS.md

Project rules; commit to Git

~/.config/opencode/AGENTS.md

Global personal rules

CLAUDE.md, ~/.claude/CLAUDE.md

Fallback compatibility

instructions

Extra files/globs/remote URLs; combined with rules

OPENCODE_DISABLE_CLAUDE_CODE*

Disable Claude compatibility pieces

.opencode/plugins/*.js / .ts

Project plugin

~/.config/opencode/plugins/*.js / .ts

Global plugin

plugin: ["pkg", "@scope/pkg"]

Load npm plugins

.opencode/package.json

Dependencies for local plugins/tools

tool.execute.before/after

Inspect or alter tool calls

shell.env, permission.*, session.*, tui.*, lsp.*

Common hook areas

Plugin tool export

Add tools; name collision overrides built-in

Enable formatters

"formatter": true or {}

Disable formatters

Omit formatter or set false

Custom formatter

formatter.<name>.command, extensions, environment; use $FILE

Enable LSP

"lsp": true or {}

Disable LSP

Omit lsp or set false

Custom LSP

lsp.<name>.command, extensions, env, initialization

Disable LSP downloads

OPENCODE_DISABLE_LSP_DOWNLOAD=true

Enable LSP tool

OPENCODE_EXPERIMENTAL_LSP_TOOL=true

/themes

Select/list themes

tui.json: "theme": "tokyonight"

Persist theme

system

Match terminal background/ANSI palette

Built-ins

opencode, tokyonight, everforest, ayu, catppuccin, gruvbox, kanagawa, nord, matrix, one-dark

Custom themes

~/.config/opencode/themes/*.json or .opencode/themes/*.json

Truecolor

Set COLORTERM=truecolor if needed

OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_CONFIG_CONTENT

Config overrides

OPENCODE_TUI_CONFIG

TUI config path

OPENCODE_PERMISSION

Inline permissions JSON

OPENCODE_SERVER_PASSWORD, OPENCODE_SERVER_USERNAME

Basic auth for serve/web

OPENCODE_AUTO_SHARE

Auto-share sessions

OPENCODE_DISABLE_AUTOUPDATE, OPENCODE_DISABLE_AUTOCOMPACT

Disable update/compaction behavior

OPENCODE_DISABLE_DEFAULT_PLUGINS, OPENCODE_DISABLE_LSP_DOWNLOAD, OPENCODE_DISABLE_MODELS_FETCH

Disable default loading/fetching

OPENCODE_DISABLE_MOUSE

Disable TUI mouse capture

OPENCODE_GIT_BASH_PATH

Git Bash path on Windows

OPENCODE_ENABLE_EXA

Enable Exa web search tools

OPENCODE_EXPERIMENTAL*

Experimental features

/share

Public opncd.ai/s/<id> link

/unshare

Remove public link/data

"share": "manual"

Default

"share": "auto"

Share new conversations automatically

"share": "disabled"

Disable sharing

Recommended Windows setup

Use WSL for better file performance and terminal compatibility

Install in WSL

`curl -fsSL https://opencode.ai/install

Access Windows files

cd /mnt/c/Users/YourName/project && opencode

Best performance

Clone repos into WSL filesystem, e.g. ~/code/

Serve from WSL

opencode serve --hostname 0.0.0.0 --port 4096

Secure WSL server

OPENCODE_SERVER_PASSWORD=... opencode serve --hostname 0.0.0.0

Web from WSL

opencode web --hostname 0.0.0.0; open printed URL in Windows browser

Logs

macOS/Linux ~/.local/share/opencode/log/; Windows %USERPROFILE%\.local\share\opencode\log

App data

macOS/Linux ~/.local/share/opencode/; Windows %USERPROFILE%\.local\share\opencode

Debug logs

opencode --print-logs --log-level DEBUG

Won't start

Check logs, use --print-logs, then opencode upgrade

Auth issues

Re-run /connect; verify keys and network

Model missing

Check exact provider/model, auth, and opencode models

ProviderInitError

Fix provider config; last resort clear ~/.local/share/opencode and reconnect

API/provider package errors

Clear ~/.cache/opencode and restart

Desktop crash/hang

Disable plugin config and move plugin dirs aside

Desktop connection failed

Clear default server URL; remove server.port/hostname; unset OPENCODE_PORT

Linux blank desktop window

Try OC_ALLOW_WAYLAND=1 or X11

Windows blank desktop window

Install/update Edge WebView2 Runtime

Linux copy/paste

Install xclip, xsel, or wl-clipboard

Ask about code

How is auth handled in @src/api.ts?

Plan first

Switch to plan with Tab, describe goal, iterate

Build after plan

Switch back to build, ask to implement

Include command output

!npm test or npm test in a command template

Fix by example

Reference target and known-good file: @settings.ts + @notes.ts

Recover bad change

/undo, adjust prompt, rerun

Restore undone work

/redo

Share context

/share; remove with /unshare