# OpenCode CLI & TUI Usage

# OpenCode CLI & TUI Complete Usage Guide

A comprehensive guide covering keyboard shortcuts, interface modes, configuration, and best practices for the OpenCode interactive CLI/TUI agent.

---

## 1. Core UI Navigation & Keybinds

OpenCode uses a **Leader Key** system to avoid conflicts with terminal or shell shortcuts.
- **Default Leader Key:** `Ctrl+X`
- **Leader Timeout:** 2000 ms (press `<leader>` then the command key within 2 seconds).

### Interface & Display Controls

| Action | Default Shortcut | Config Key | Description |
| :--- | :--- | :--- | :--- |
| **Toggle Sidebar** | `<leader> b` (`Ctrl+X` then `b`) | `sidebar_toggle` | Hides/shows the right info sidebar box. |
| **Open Command Palette** | `Ctrl+P` | `command_list` | Opens prompt command list for quick actions. |
| **Toggle Tips** | `<leader> h` | `tips_toggle` | Toggle onscreen contextual tips. |
| **Exit OpenCode** | `Ctrl+C`, `Ctrl+D`, or `<leader> q` | `app_exit` | Quit the application session. |
| **Suspend Terminal** | `Ctrl+Z` | `terminal_suspend` | Suspend process to background (POSIX shells). |
| **Which-Key Popup** | `Ctrl+Alt+K` | `which_key_toggle` | Display interactive keybind map. |

---

### Session Management

| Action | Shortcut | Config Key | Description |
| :--- | :--- | :--- | :--- |
| **New Session** | `<leader> n` | `session_new` | Start a fresh agent chat session. |
| **List Sessions** | `<leader> l` | `session_list` | Open interactive session picker. |
| **Session Timeline** | `<leader> g` | `session_timeline` | View session branching and event history. |
| **Export Session** | `<leader> x` | `session_export` | Export session history as JSON. |
| **Compact Session** | `<leader> c` | `session_compact` | Summarize and compact long chat context. |
| **Rename Session** | `Ctrl+R` | `session_rename` | Change current session title. |
| **Delete Session** | `Ctrl+D` (in list) | `session_delete` | Permanently remove a session. |
| **Interrupt Generation** | `Esc` | `session_interrupt` | Stop model generation or tool execution. |

---

### Messages & Scroll Navigation

| Action | Shortcut | Config Key | Description |
| :--- | :--- | :--- | :--- |
| **Page Up / Down** | `PageUp` / `PageDown` | `messages_page_up` / `_down` | Scroll chat history by page. |
| **Half Page Scroll** | `Ctrl+Alt+U` / `Ctrl+Alt+D` | `messages_half_page_up` / `_down` | Scroll half page up/down. |
| **Jump to Top** | `Ctrl+G` or `Home` | `messages_first` | Jump to start of chat transcript. |
| **Jump to Bottom** | `Ctrl+Alt+G` or `End` | `messages_last` | Jump to latest response. |
| **Copy Last Message** | `<leader> y` | `messages_copy` | Copy entire last response directly to system clipboard. |
| **Undo / Redo** | `<leader> u` / `<leader> r` | `messages_undo` / `_redo` | Undo or redo chat message edits. |
| **Conceal Code** | `<leader> h` | `messages_toggle_conceal` | Fold or unfold code blocks in chat. |

---

### Models, Agents & Themes

| Action | Shortcut | Config Key | Description |
| :--- | :--- | :--- | :--- |
| **Switch Agent** | `Tab` / `Shift+Tab` | `agent_cycle` / `_reverse` | Cycle between primary/subagent modes. |
| **List Agents** | `<leader> a` | `agent_list` | Open agent selector modal. |
| **List Models** | `<leader> m` | `model_list` | Open model selection dialog. |
| **Cycle Recent Model**| `F2` / `Shift+F2` | `model_cycle_recent` | Switch to previous model. |
| **Favorite Model** | `Ctrl+F` | `model_favorite_toggle` | Toggle favorite status for selected model. |
| **Switch Theme** | `<leader> t` | `theme_list` | Select UI color theme. |
| **Cycle Variants** | `Ctrl+T` | `variant_cycle` | Toggle model reasoning effort (low/med/high). |

---

### Prompt Input Editing (Readline / Emacs)

| Shortcut | Action |
| :--- | :--- |
| `Enter` | Submit prompt |
| `Shift+Enter` / `Ctrl+J` | Insert newline |
| `Ctrl+A` / `Ctrl+E` | Move cursor to start / end of line |
| `Ctrl+B` / `Ctrl+F` | Move cursor back / forward one char |
| `Alt+B` / `Alt+F` | Move cursor back / forward one word |
| `Ctrl+K` | Kill text from cursor to end of line |
| `Ctrl+U` | Kill text from cursor to start of line |
| `Ctrl+W` | Delete word backward |
| `Alt+D` | Delete word forward |

---

## 2. Modes & Execution Options

OpenCode offers several execution modes depending on your interface and automation needs.

### 1. Standard Interactive TUI (`opencode`)
Starts the full terminal user interface with chat transcript, sidebar info pane, and status indicators.
```bash
opencode
```

### 2. Minimal Single-Column TUI (`--mini`)
Removes sidebars, borders, and multi-column widgets.
```bash
# Start new minimal session
opencode --mini

# Resume last session in minimal mode
opencode --mini -c
```

### 3. Non-Interactive CLI / Scripting (`opencode run`)
Executes a single prompt or command non-interactively without launching the TUI. Prints raw Markdown or JSON output directly to `stdout`.
```bash
# Single prompt execution
opencode run "Explain closures in Rust"

# Pass file context
opencode run -f src/main.rs "Review this code for safety"

# Output as raw JSON events
opencode run --format json "List open TODO items"
```

### 4. Headless Server & Attach (`opencode serve` / `opencode attach`)
Runs an OpenCode backend server process (avoiding cold boots for MCP plugins) that remote terminals or web clients can attach to.
```bash
# Terminal 1: Start headless backend
opencode serve --port 4096

# Terminal 2: Attach TUI from another terminal/session
opencode attach http://localhost:4096
```

---

## 3. Customizing Shortcuts (`~/.config/opencode/tui.json`)

Keybinds can be overridden globally by creating or editing `~/.config/opencode/tui.json`.

### Example `tui.json` Configuration:
```json
{
  "$schema": "https://opencode.ai/tui.json",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "sidebar_toggle": "f3",
    "messages_copy": ["<leader>y", "ctrl+shift+c"],
    "session_compact": "none"
  }
}
```

---

## 4. Copying Text Cleanly

> **Important Note on Mouse Selection:** In TUI terminals, OpenCode renders chat messages inside a fixed width box container. Even with the sidebar hidden via `<leader> b`, terminal mouse dragging selects the entire terminal row width, picking up all trailing pad spaces up to the terminal window border.

### Best Ways to Copy Code Snippets:

1. **Use Message Copy Shortcut (`<leader> y`)**:
   Press **`Ctrl+X` then `y`** to yank the entire model's latest message directly into your system clipboard without any formatting or padding issues.
2. **Use Tmux Copy Mode (`Ctrl+B [`)**:
   Use native tmux copy mode (`v` to select, `y` to copy via OSC 52).
3. **Use CLI Run Mode (`opencode run ...`)**:
   Run single queries via `opencode run` to print raw, un-padded Markdown straight to standard output.