2025-12-01 11:38:48 -08:00
# Gemini CLI keyboard shortcuts
2025-07-28 15:35:06 -04:00
2025-11-12 16:07:14 -05:00
Gemini CLI ships with a set of default keyboard shortcuts for editing input,
navigating history, and controlling the UI. Use this reference to learn the
available combinations.
<!-- KEYBINDINGS-AUTOGEN:START -->
#### Basic Controls
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| --------------- | --------------------------------------------------------------- | ------------------- |
| `basic.confirm` | Confirm the current selection or choice. | `Enter` |
| `basic.cancel` | Dismiss dialogs or cancel the current focus. | `Esc` <br />`Ctrl+[` |
| `basic.quit` | Cancel the current request or quit the CLI when input is empty. | `Ctrl+C` |
| `basic.exit` | Exit the CLI when the input buffer is empty. | `Ctrl+D` |
2025-11-12 16:07:14 -05:00
#### Cursor Movement
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ------------------ | ------------------------------------------- | ------------------------------------------ |
| `cursor.home` | Move the cursor to the start of the line. | `Ctrl+A` <br />`Home` |
| `cursor.end` | Move the cursor to the end of the line. | `Ctrl+E` <br />`End` |
| `cursor.up` | Move the cursor up one line. | `Up` |
| `cursor.down` | Move the cursor down one line. | `Down` |
| `cursor.left` | Move the cursor one character to the left. | `Left` |
| `cursor.right` | Move the cursor one character to the right. | `Right` <br />`Ctrl+F` |
| `cursor.wordLeft` | Move the cursor one word to the left. | `Ctrl+Left` <br />`Alt+Left` <br />`Alt+B` |
| `cursor.wordRight` | Move the cursor one word to the right. | `Ctrl+Right` <br />`Alt+Right` <br />`Alt+F` |
2025-11-12 16:07:14 -05:00
#### Editing
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ---------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| `edit.deleteRightAll` | Delete from the cursor to the end of the line. | `Ctrl+K` |
| `edit.deleteLeftAll` | Delete from the cursor to the start of the line. | `Ctrl+U` |
| `edit.clear` | Clear all text in the input field. | `Ctrl+C` |
| `edit.deleteWordLeft` | Delete the previous word. | `Ctrl+Backspace` <br />`Alt+Backspace` <br />`Ctrl+W` |
| `edit.deleteWordRight` | Delete the next word. | `Ctrl+Delete` <br />`Alt+Delete` <br />`Alt+D` |
| `edit.deleteLeft` | Delete the character to the left. | `Backspace` <br />`Ctrl+H` |
| `edit.deleteRight` | Delete the character to the right. | `Delete` <br />`Ctrl+D` |
| `edit.undo` | Undo the most recent text edit. | `Cmd/Win+Z` <br />`Alt+Z` |
| `edit.redo` | Redo the most recent undone text edit. | `Ctrl+Shift+Z` <br />`Shift+Cmd/Win+Z` <br />`Alt+Shift+Z` |
2025-11-12 16:07:14 -05:00
2025-11-13 11:16:23 -08:00
#### Scrolling
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ----------------- | ------------------------ | ----------------------------- |
| `scroll.up` | Scroll content up. | `Shift+Up` |
| `scroll.down` | Scroll content down. | `Shift+Down` |
| `scroll.home` | Scroll to the top. | `Ctrl+Home` <br />`Shift+Home` |
| `scroll.end` | Scroll to the bottom. | `Ctrl+End` <br />`Shift+End` |
| `scroll.pageUp` | Scroll up by one page. | `Page Up` |
| `scroll.pageDown` | Scroll down by one page. | `Page Down` |
2025-11-13 11:16:23 -08:00
2025-11-12 16:07:14 -05:00
#### History & Search
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ----------------------- | -------------------------------------------- | -------- |
| `history.previous` | Show the previous entry in history. | `Ctrl+P` |
| `history.next` | Show the next entry in history. | `Ctrl+N` |
| `history.search.start` | Start reverse search through history. | `Ctrl+R` |
| `history.search.submit` | Submit the selected reverse-search match. | `Enter` |
| `history.search.accept` | Accept a suggestion while reverse searching. | `Tab` |
2025-11-12 16:07:14 -05:00
#### Navigation
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| --------------------- | -------------------------------------------------- | --------------- |
| `nav.up` | Move selection up in lists. | `Up` |
| `nav.down` | Move selection down in lists. | `Down` |
| `nav.dialog.up` | Move up within dialog options. | `Up` <br />`K` |
| `nav.dialog.down` | Move down within dialog options. | `Down` <br />`J` |
| `nav.dialog.next` | Move to the next item or question in a dialog. | `Tab` |
| `nav.dialog.previous` | Move to the previous item or question in a dialog. | `Shift+Tab` |
2025-11-12 16:07:14 -05:00
#### Suggestions & Completions
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ----------------------- | --------------------------------------- | -------------------- |
| `suggest.accept` | Accept the inline suggestion. | `Tab` <br />`Enter` |
| `suggest.focusPrevious` | Move to the previous completion option. | `Up` <br />`Ctrl+P` |
| `suggest.focusNext` | Move to the next completion option. | `Down` <br />`Ctrl+N` |
| `suggest.expand` | Expand an inline suggestion. | `Right` |
| `suggest.collapse` | Collapse an inline suggestion. | `Left` |
2025-11-12 16:07:14 -05:00
#### Text Input
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| -------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `input.submit` | Submit the current prompt. | `Enter` |
| `input.newline` | Insert a newline without submitting. | `Ctrl+Enter` <br />`Cmd/Win+Enter` <br />`Alt+Enter` <br />`Shift+Enter` <br />`Ctrl+J` |
| `input.openExternalEditor` | Open the current prompt or the plan in an external editor. | `Ctrl+X` |
| `input.paste` | Paste from the clipboard. | `Ctrl+V` <br />`Cmd/Win+V` <br />`Alt+V` |
2025-11-12 16:07:14 -05:00
#### App Controls
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `app.showErrorDetails` | Toggle detailed error information. | `F12` |
| `app.showFullTodos` | Toggle the full TODO list. | `Ctrl+T` |
| `app.showIdeContextDetail` | Show IDE context details. | `Ctrl+G` |
| `app.toggleMarkdown` | Toggle Markdown rendering. | `Alt+M` |
| `app.toggleCopyMode` | Toggle copy mode when in alternate buffer mode. | `Ctrl+S` |
| `app.toggleYolo` | Toggle YOLO (auto-approval) mode for tool calls. | `Ctrl+Y` |
| `app.cycleApprovalMode` | Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). Plan mode is skipped when the agent is busy. | `Shift+Tab` |
| `app.showMoreLines` | Expand and collapse blocks of content when not in alternate buffer mode. | `Ctrl+O` |
| `app.expandPaste` | Expand or collapse a paste placeholder when cursor is over placeholder. | `Ctrl+O` |
| `app.focusShellInput` | Move focus from Gemini to the active shell. | `Tab` |
| `app.unfocusShellInput` | Move focus from the shell back to Gemini. | `Shift+Tab` |
| `app.clearScreen` | Clear the terminal screen and redraw the UI. | `Ctrl+L` |
| `app.restart` | Restart the application. | `R` <br />`Shift+R` |
| `app.suspend` | Suspend the CLI and move it to the background. | `Ctrl+Z` |
| `app.showShellUnfocusWarning` | Show warning when trying to move focus away from shell input. | `Tab` |
2026-03-10 19:15:45 +00:00
#### Background Shell Controls
2026-03-11 14:25:24 +00:00
| Command | Action | Keys |
| --------------------------- | ------------------------------------------------------------------ | ----------- |
| `background.escape` | Dismiss background shell list. | `Esc` |
| `background.select` | Confirm selection in background shell list. | `Enter` |
| `background.toggle` | Toggle current background shell visibility. | `Ctrl+B` |
| `background.toggleList` | Toggle background shell list. | `Ctrl+L` |
| `background.kill` | Kill the active background shell. | `Ctrl+K` |
| `background.unfocus` | Move focus from background shell to Gemini. | `Shift+Tab` |
| `background.unfocusList` | Move focus from background shell list to Gemini. | `Tab` |
| `background.unfocusWarning` | Show warning when trying to move focus away from background shell. | `Tab` |
2025-11-12 16:07:14 -05:00
<!-- KEYBINDINGS-AUTOGEN:END -->
2026-03-11 14:25:24 +00:00
## Customizing Keybindings
You can add alternative keybindings for commands by creating or modifying the
`keybindings.json` file in your home gemini directory (typically
`~/.gemini/keybindings.json` ). This allows you to bind commands to additional
key combinations. Note that default keybindings cannot be removed.
### Configuration Format
The configuration uses a JSON array of objects, similar to VS Code's keybinding
schema. Each object must specify a `command` from the reference tables above and
a `key` combination.
```json
[
{
"command": "input.submit",
"key": "cmd+s"
},
{
"command": "edit.clear",
"key": "ctrl+l"
}
]
```
### Keyboard Rules
- **Explicit Modifiers**: Key matching is explicit. For example, a binding for
`ctrl+f` will only trigger on exactly `ctrl+f` , not `ctrl+shift+f` or
`alt+ctrl+f` . You must specify the exact modifier keys (`ctrl` , `shift` ,
`alt` /`opt` /`option` , `cmd` /`meta` ).
- **Literal Characters**: Terminals often translate complex key combinations
(especially on macOS with the `Option` key) into special characters. To handle
this reliably across all operating systems and SSH sessions, you can bind
directly to the literal character produced. For example, instead of trying to
bind `shift+5` , bind directly to `%` .
- **Special Keys**: Supported special keys include:
- **Navigation**: `up` , `down` , `left` , `right` , `home` , `end` , `pageup` ,
`pagedown`
- **Actions**: `enter` , `escape` , `tab` , `space` , `backspace` , `delete` ,
`clear` , `insert` , `printscreen`
- **Toggles**: `capslock` , `numlock` , `scrolllock` , `pausebreak`
- **Function Keys**: `f1` through `f35`
- **Numpad**: `numpad0` through `numpad9` , `numpad_add` , `numpad_subtract` ,
`numpad_multiply` , `numpad_divide` , `numpad_decimal` , `numpad_separator`
2025-12-01 11:38:48 -08:00
## Additional context-specific shortcuts
2025-11-12 16:07:14 -05:00
2026-01-12 16:28:10 -08:00
- `Option+B/F/M` (macOS only): Are interpreted as `Cmd+B/F/M` even if your
terminal isn't configured to send Meta with Option.
2025-11-12 16:07:14 -05:00
- `!` on an empty prompt: Enter or exit shell mode.
2026-02-06 11:33:39 -08:00
- `?` on an empty prompt: Toggle the shortcuts panel above the input. Press
2026-02-12 11:35:40 -05:00
`Esc` , `Backspace` , any printable key, or a registered app hotkey to close it.
The panel also auto-hides while the agent is running/streaming or when
action-required dialogs are shown. Press `?` again to close the panel and
insert a `?` into the prompt.
2026-02-12 14:25:24 -05:00
- `Tab` + `Tab` (while typing in the prompt): Toggle between minimal and full UI
details when no completion/search interaction is active. The selected mode is
remembered for future sessions. Full UI remains the default on first run, and
single `Tab` keeps its existing completion/focus behavior.
2026-02-17 12:36:59 -05:00
- `Shift + Tab` (while typing in the prompt): Cycle approval modes: default,
auto-edit, and plan (skipped when agent is busy).
2025-11-12 16:07:14 -05:00
- `\` (at end of a line) + `Enter` : Insert a newline without leaving single-line
mode.
2026-01-20 19:32:26 -05:00
- `Esc` pressed twice quickly: Clear the input prompt if it is not empty,
otherwise browse and rewind previous interactions.
2025-11-12 16:07:14 -05:00
- `Up Arrow` / `Down Arrow` : When the cursor is at the top or bottom of a
single-line input, navigate backward or forward through prompt history.
- `Number keys (1-9, multi-digit)` inside selection dialogs: Jump directly to
the numbered radio option and confirm when the full number is entered.
2026-02-09 21:04:34 -05:00
- `Ctrl + O` : Expand or collapse paste placeholders (`[Pasted Text: X lines]` )
inline when the cursor is over the placeholder.
- `Double-click` on a paste placeholder (alternate buffer mode only): Expand to
view full content inline. Double-click again to collapse.
2026-03-02 12:31:52 -08:00
## Limitations
- On [Windows Terminal ](https://en.wikipedia.org/wiki/Windows_Terminal ):
2026-03-05 22:11:53 +00:00
- `shift+enter` is only supported in version 1.25 and higher.
2026-03-02 12:31:52 -08:00
- `shift+tab`
[is not supported ](https://github.com/google-gemini/gemini-cli/issues/20314 )
on Node 20 and earlier versions of Node 22.
- On macOS's [Terminal ](<https://en.wikipedia.org/wiki/Terminal_(macOS )>):
- `shift+enter` is not supported.
