q",
- "app.debug": "none",
- "help.show": false
},
- "leader": {
- "timeout": 2000
+ "animations": true,
+ "cursor": {
+ "style": "block",
+ "blinking": true
}
}
```
-See [Keybinds](/cli/keybinds) for every available binding.
+
-## Plugins
+| Setting | Values | Description |
+| ----------------- | --------------------------------------- | ------------------------------------------------------------------------ |
+| `theme.name` | string | Selects a built-in, custom, or terminal-derived theme. |
+| `theme.mode` | `system`, `dark`, or `light` | Follows the terminal appearance or locks the theme to one color mode. |
+| `animations` | boolean | Enables interface animations. |
+| `cursor.style` | `block`, `underline`, `line`, `default` | Sets the cursor shape. `default` preserves the terminal's cursor shape. |
+| `cursor.blinking` | boolean | Controls cursor blinking. It has no effect when the style is `default`. |
-Load terminal plugins in order:
-
-```json title="cli.json"
-{
- "plugins": [
- "-opencode.notifications",
- {
- "package": "./plugins/status",
- "options": {
- "compact": true
- }
- }
- ]
-}
-```
-
-See [Plugins](/cli/plugins) for packages, local plugins, options, and enablement directives.
-
-## Scroll
-
-Set scroll speed and acceleration:
+
+
+See [Theme](/cli/theme) for selecting and creating themes.
+
+## Input
+
+Configure mouse capture, scrolling, editor context, pastes, and prompt image previews:
```json title="cli.json"
{
+ "mouse": true,
"scroll": {
- "speed": 2,
- "acceleration": true
+ "speed": 3,
+ "acceleration": false
+ },
+ "prompt": {
+ "editor": true,
+ "paste": "compact",
+ "image_preview": false
}
}
```
-| Field | Values | Description |
-| -------------- | ------------------------ | --------------------------------- |
-| `speed` | number, at least `0.001` | Sets the distance per input tick. |
-| `acceleration` | boolean | Speeds up repeated scrolling. |
+
-## Attention
+| Setting | Values | Description |
+| -------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
+| `mouse` | boolean | Enables terminal mouse capture. |
+| `scroll.speed` | number, at least `0.001` | Sets the fixed distance per scroll input tick. |
+| `scroll.acceleration` | boolean | Accelerates repeated scrolling. When enabled, it takes precedence over speed. |
+| `prompt.editor` | boolean | Includes the active editor file or selection as prompt context. |
+| `prompt.paste` | `compact` or `full` | Shows large pastes as compact placeholders or as full text. |
+| `prompt.image_preview` | boolean | Shows image attachment previews above the prompt input. |
-Configure notifications and sounds. Both are off by default and can be enabled independently:
+
+
+## Sessions
+
+Configure how full-screen TUI sessions are presented and where new sessions start:
+
+```json title="cli.json"
+{
+ "session": {
+ "sidebar": "auto",
+ "scrollbar": false,
+ "thinking": "hide",
+ "grouping": "auto",
+ "image_preview": false,
+ "tps": true,
+ "markdown": "rendered",
+ "new_location": "launch",
+ "permissions": "prompt"
+ }
+}
+```
+
+
+
+| Setting | Values | Description |
+| ----------------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| `session.sidebar` | `auto` or `hide` | Shows the sidebar when space permits or always hides it. |
+| `session.scrollbar` | boolean | Shows the transcript scrollbar. |
+| `session.thinking` | `show` or `hide` | Shows or hides model reasoning by default. |
+| `session.grouping` | `auto` or `none` | Groups related transcript items or renders each item separately. |
+| `session.image_preview` | boolean | Shows user attachment and tool-result images in the transcript. |
+| `session.tps` | boolean | Shows output tokens per second in assistant footers. |
+| `session.markdown` | `source` or `rendered` | Shows Markdown syntax markers or conceals them in rendered content. |
+| `session.new_location` | `launch` or `inherit` | Starts in the TUI launch directory or inherits the active session location. |
+| `session.permissions` | `prompt` or `autoaccept` | Prompts for permission requests or accepts every request automatically. |
+
+
+
+## Tabs
+
+Configure the persistent session tab strip:
+
+```json title="cli.json"
+{
+ "tabs": {
+ "enabled": true,
+ "scope": "cwd",
+ "layout": "horizontal",
+ "indicators": "status"
+ }
+}
+```
+
+
+
+| Setting | Values | Description |
+| ----------------- | --------------------------- | ----------------------------------------------------------------------------- |
+| `tabs.enabled` | boolean | Uses a persistent tab strip instead of pinned quick-switch sessions. |
+| `tabs.scope` | `cwd` or `global` | Keeps separate tabs per working directory or shares them globally. |
+| `tabs.layout` | `horizontal` or `vertical` | Places tabs in a horizontal strip or a vertical sidebar. |
+| `tabs.indicators` | `status` or `numbers` | Shows status icons or always shows tab numbers. |
+
+
+
+Number indicators retain status colors and background animations. Ctrl+number shortcuts switch tabs in either indicator
+mode.
+
+## Diffs
+
+Configure the initial diff scope and presentation:
+
+```json title="cli.json"
+{
+ "diffs": {
+ "source": "branch",
+ "wrap": "word",
+ "tree": true,
+ "single": false,
+ "view": "auto"
+ }
+}
+```
+
+
+
+| Setting | Values | Description |
+| -------------- | ----------------------------------- | ------------------------------------------------------------- |
+| `diffs.source` | `branch`, `committed`, or `working` | Sets the initial review scope. |
+| `diffs.wrap` | `word` or `none` | Wraps long lines at words or leaves them unwrapped. |
+| `diffs.tree` | boolean | Shows the diff file tree. |
+| `diffs.single` | boolean | Shows only the selected file patch. |
+| `diffs.view` | `auto`, `split`, or `unified` | Sets the layout. `auto` chooses from the available width. |
+
+
+
+`branch` shows **All** branch and local changes, `committed` shows branch commits only, and `working` shows staged,
+unstaged, and untracked changes.
+
+In `/diff`, press `d` to change the scope or choose a comparison branch from **Base**. These in-view choices last until
+the TUI exits and do not change `cli.json`.
+
+## Alerts
+
+Enable system notifications and attention sounds independently:
```json title="cli.json"
{
@@ -135,73 +227,19 @@ Configure notifications and sounds. Both are off by default and can be enabled i
}
```
-| Field | Values | Description |
-| --------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
-| `notifications` | boolean | Shows system notifications when the terminal is not focused. |
-| `sound` | boolean | Plays attention sounds. |
-| `volume` | number from `0` to `1` | Sets sound volume. |
-| `sound_pack` | string | Selects the active sound pack. |
-| `sounds` | object | Overrides files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done` events. |
+
-## Session
+| Setting | Values | Description |
+| ------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `attention.notifications` | boolean | Shows system notifications, normally when the terminal is not focused. |
+| `attention.sound` | boolean | Plays attention sounds. |
+| `attention.volume` | number from `0` to `1` | Sets sound volume. |
+| `attention.sound_pack` | string | Selects the active sound pack ID. |
+| `attention.sounds` | object | Overrides sound files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done`. |
-Choose whether the TUI prompts before granting permission requests:
+
-```json title="cli.json"
-{
- "session": {
- "permissions": "prompt"
- }
-}
-```
-
-| Field | Values | Description |
-| ------------- | ------------------------ | ----------------------------------------------------------------------- |
-| `permissions` | `prompt` or `autoaccept` | Prompts for permission requests or accepts every request automatically. |
-
-## Diffs
-
-Configure diff presentation:
-
-```json title="cli.json"
-{
- "diffs": {
- "source": "branch",
- "wrap": "word",
- "tree": true,
- "single": false,
- "view": "auto"
- }
-}
-```
-
-| Field | Values | Description |
-| -------- | ----------------------------------- | ------------------------------------------------------------- |
-| `source` | `branch`, `committed`, or `working` | Sets the initial review scope. Defaults to `branch`. |
-| `wrap` | `word` or `none` | Sets line wrapping. |
-| `tree` | boolean | Shows the diff file tree. |
-| `single` | boolean | Shows only the selected file patch. |
-| `view` | `auto`, `split`, or `unified` | Sets the layout. `auto` chooses based on the available width. |
-
-`branch` shows **All** (branch and local changes), `committed` shows **Committed** (branch commits only), and `working` shows **Uncommitted** (staged, unstaged, and untracked changes).
-
-In `/diff`, press `d` to change the scope or choose a comparison branch from **Base**. OpenCode infers the base from local Git history when possible; otherwise it asks you to choose before loading a branch diff.
-
-Your base choice for each branch and last selected scope survive closing and reopening the viewer, but reset when the TUI exits. These selections do not change `cli.json`.
-
-## Tabs
-
-Choose **Tabs > Indicators** in settings, or set `tabs.indicators` in `cli.json`:
-
-```json title="cli.json"
-{
- "tabs": {
- "indicators": "numbers"
- }
-}
-```
-
-`status` (the default) shows status icons. `numbers` always shows tab numbers, retaining their status colors and background animations. Both modes work with horizontal and vertical tabs. Ctrl+number shortcuts switch tabs in either mode.
+An invalid or unreadable override falls back to the built-in sound for that event.
## Terminal
@@ -216,7 +254,158 @@ Configure terminal integration:
}
```
-| Field | Values | Description |
-| ------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
-| `title` | boolean | Updates the terminal window title. |
-| `copy` | `manual` or `select` | Sets manual copy or copy on selection. Defaults to `select` on macOS and Linux, and `manual` on Windows. |
+
+
+| Setting | Values | Description |
+| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `terminal.title` | boolean | Updates the terminal window title. |
+| `terminal.copy` | `manual` or `select` | Copies manually or immediately after selection. The platform default is `manual` on Windows and `select` elsewhere. |
+
+
+
+## Mini
+
+The `mini` group controls [`opencode mini`](/cli#mini), the minimal interactive interface:
+
+```json title="cli.json"
+{
+ "mini": {
+ "thinking": "show",
+ "tools": "hide",
+ "shell_output": "hide",
+ "turn_summary": "show",
+ "footer": "show",
+ "splash": "show",
+ "work_spinner": "block-soft-slide",
+ "mono": false,
+ "replay": true,
+ "replay_limit": 200
+ }
+}
+```
+
+
+
+| Setting | Values | Description |
+| ------------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
+| `mini.thinking` | `show` or `hide` | Shows or hides model reasoning. |
+| `mini.tools` | `show` or `hide` | Shows or hides tool calls and the assistant text that precedes them. |
+| `mini.shell_output` | `show` or `hide` | Shows or hides raw shell tool output. |
+| `mini.turn_summary` | `show` or `hide` | Shows or hides the agent, model, and duration summary in scrollback. |
+| `mini.footer` | `show` or `hide` | Shows or hides persistent activity, model, usage, and context details. |
+| `mini.splash` | `show` or `hide` | Shows or hides entry and exit splash banners. |
+| `mini.work_spinner` | spinner ID | Selects the work animation in the footer. |
+| `mini.mono` | boolean | Uses monochrome ASCII output. |
+| `mini.replay` | boolean | Restores session history on resume and terminal resize. |
+| `mini.replay_limit` | positive integer | Limits replay to the newest messages. The default limit is `200`. |
+
+
+
+Available spinner IDs are:
+
+```text
+block-soft-slide block-soft-sweep block-low-comet block-low-duet
+block-shuttle block-bridge block-squeeze small-toggle
+square-toggle grow-shrink quadrant-orbit crosshatch
+density-wave seed
+```
+
+Command-line `mini` replay flags override these settings for that invocation.
+
+## Keybinds
+
+Override a command binding and the leader-key timeout:
+
+```json title="cli.json"
+{
+ "keybinds": {
+ "leader": "ctrl+x",
+ "app.exit": ["ctrl+c", "ctrl+d", "q"],
+ "prompt.paste": {
+ "key": "ctrl+v",
+ "event": "press",
+ "preventDefault": false,
+ "fallthrough": false
+ },
+ "help.show": false
+ },
+ "leader": {
+ "timeout": 2000
+ }
+}
+```
+
+
+
+| Setting | Values | Description |
+| ----------------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
+| `keybinds.leader` | binding value | Sets the key referenced by `` in other bindings. |
+| `keybinds.` | binding value | Overrides the binding for one command ID. |
+| `keybinds.*.key` | key string or descriptor | Selects the key for an object binding. |
+| `keybinds.*.event` | `press` or `release` | Limits an object binding to one key event. |
+| `keybinds.*.preventDefault` | boolean | Controls whether the terminal's default key behavior is prevented. |
+| `keybinds.*.fallthrough` | boolean | Allows lower-priority handlers to receive the same event. |
+| `leader.timeout` | positive integer | Sets how many milliseconds to wait after the leader key. |
+
+
+
+A binding value can be a string, an array of alternatives, or an object. Use `"none"` or `false` to disable a binding.
+See [Keybinds](/cli/keybinds) for accepted key syntax, every command ID, and every default binding.
+
+## Plugins
+
+Load terminal-only plugins in order:
+
+```json title="cli.json"
+{
+ "plugins": [
+ "-opencode.notifications",
+ {
+ "package": "./plugins/status",
+ "options": {
+ "compact": true
+ }
+ }
+ ]
+}
+```
+
+
+
+| Setting | Values | Description |
+| -------------------- | --------------- | --------------------------------------------------------------- |
+| `plugins` | array | Declares ordered enablement directives and external plugins. |
+| `plugins[].package` | string | Sets a package name, local path, or file URL. |
+| `plugins[].options` | object | Passes plugin-specific options to that plugin. |
+
+
+
+See [Plugins](/cli/plugins) for package forms, local discovery, wildcards, and disable directives.
+
+## Debug and experimental
+
+Enable diagnostics or opt in to a currently available experiment:
+
+```json title="cli.json"
+{
+ "debug": {
+ "devtools": false,
+ "timing": false,
+ "turn_tokens": "verbose"
+ },
+ "experimental": {}
+}
+```
+
+
+
+| Setting | Values | Description |
+| ------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
+| `debug.devtools` | boolean | Shows the DevTools debug bar. |
+| `debug.timing` | boolean | Shows time-to-first-draw diagnostics in the debug bar. |
+| `debug.turn_tokens` | boolean or `verbose` | Shows per-turn token usage; `verbose` also includes tool call inputs. |
+| `experimental` | object of feature IDs to booleans | Enables or disables experiments that may change or be removed without notice. |
+
+
+
+Only use feature IDs currently listed by the TUI's **Experiments** dialog. Unknown IDs have no effect.
diff --git a/services/www/src/docs/content/cli/theme.mdx b/services/www/src/docs/content/cli/theme.mdx
index f43fccefeef..f8096c589f1 100644
--- a/services/www/src/docs/content/cli/theme.mdx
+++ b/services/www/src/docs/content/cli/theme.mdx
@@ -8,7 +8,7 @@ OpenCode includes built-in light and dark themes. Choose a color scheme in setti
Press `Ctrl+P`, then select **Open settings** to change the theme and color mode.
-You can also set them in your global [CLI config](/cli/config):
+You can also set them in your global [CLI settings](/cli/config):
```json title="~/.config/opencode/cli.json"
{
diff --git a/services/www/src/docs/content/index.mdx b/services/www/src/docs/content/index.mdx
index c0115fb51d2..3985459f896 100644
--- a/services/www/src/docs/content/index.mdx
+++ b/services/www/src/docs/content/index.mdx
@@ -46,4 +46,4 @@ plan that grants you access to the best open source models.
Make OpenCode your own by editing the [OpenCode config](/config), [loading plugins](/plugins), [connecting MCP
servers](/mcp-servers), or [creating commands](/commands). For terminal interface themes and keybindings, see [CLI
-configuration](/cli/config).
+settings](/cli/config).
diff --git a/services/www/src/docs/content/migrate-v1.mdx b/services/www/src/docs/content/migrate-v1.mdx
index 511cd0e0877..a20a9fb717f 100644
--- a/services/www/src/docs/content/migrate-v1.mdx
+++ b/services/www/src/docs/content/migrate-v1.mdx
@@ -524,7 +524,7 @@ V2 replaces layered V1 `tui.json(c)` files with one global terminal client confi
The terminal client owns this file; the background service does not load it. When `cli.json` is absent, the first V2
terminal client startup migrates supported global `tui.json` settings and persisted preferences while leaving V1 files
unchanged. Project-local client configuration is not migrated because V2 client configuration is global. See
-[CLI config](/cli/config) for current client settings.
+[CLI settings](/cli/config) for the current client settings reference.
## Plugins
diff --git a/services/www/src/docs/content/themes.mdx b/services/www/src/docs/content/themes.mdx
index 1491013b761..6720980dc53 100644
--- a/services/www/src/docs/content/themes.mdx
+++ b/services/www/src/docs/content/themes.mdx
@@ -15,7 +15,7 @@ set it directly in your global CLI config:
```
Themes belong to the terminal client. Put theme selection in `cli.json`, not `opencode.json`. See
-[CLI config](/cli/config) for the config location and other terminal settings.
+[CLI settings](/cli/config) for the config location and other terminal settings.
## Modes
diff --git a/services/www/src/docs/lib/navigation.ts b/services/www/src/docs/lib/navigation.ts
index a4e8bc9451f..bfb14b9a8fd 100644
--- a/services/www/src/docs/lib/navigation.ts
+++ b/services/www/src/docs/lib/navigation.ts
@@ -69,7 +69,7 @@ export const docsSections: DocsSection[] = [
items: [
{ title: "Intro", slug: "cli" },
{ title: "TUI", slug: "cli/tui" },
- { title: "Config", slug: "cli/config" },
+ { title: "Settings", slug: "cli/config" },
{ title: "Web", slug: "cli/web" },
{ title: "Providers", slug: "cli/providers" },
{ title: "Commands", slug: "cli/commands" },
-The default CLI config location is:
+## Configuration file
+
+OpenCode stores CLI settings in one global file:
```text
~/.config/opencode/cli.json
```
-Set `$XDG_CONFIG_HOME` to use a different config directory:
+When `$XDG_CONFIG_HOME` is set, OpenCode uses:
```text
$XDG_CONFIG_HOME/opencode/cli.json
```
-Add the published JSON Schema for editor validation and autocomplete:
+There is no project-local CLI settings file. Add the published JSON Schema for validation and autocomplete:
```json title="cli.json"
{
@@ -26,7 +32,8 @@ Add the published JSON Schema for editor validation and autocomplete:
}
```
-OpenCode includes this automatically when it creates or migrates your CLI config.
+OpenCode adds `$schema` when it creates or migrates this file. Unknown settings are rejected, and valid edits reload
+while the TUI is running.
## Inline config
@@ -39,87 +46,172 @@ OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"enabled":false}}' opencode
OpenCode merges the inline settings over the global `cli.json`. Nested objects are merged, while arrays and scalar
values from the environment replace global values. Inline settings remain authoritative while the variable is set.
-## Theme
+## Appearance
-Set the theme and color mode:
+Choose a theme, control interface motion, and override the terminal cursor:
```json title="cli.json"
{
"theme": {
"name": "tokyonight",
"mode": "system"
- }
-}
-```
-
-| Field | Values | Description |
-| ------ | ---------------------------- | ----------------------------------------------------------------- |
-| `name` | string | Selects the theme. |
-| `mode` | `system`, `dark`, or `light` | Selects the color mode. `system` follows the terminal appearance. |
-
-See [Theme](/cli/theme) for theme configuration.
-
-## Keybinds
-
-Override bindings with the top-level `keybinds` object:
-
-```json title="cli.json"
-{
- "keybinds": {
- "leader": "ctrl+x",
- "app.exit": "ctrl+c,ctrl+d,