MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-16 17:11:04 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into galzahavi/add/sandboxManager

Browse Source
This commit is contained in:
Gal Zahavi
2026-03-11 10:06:09 -07:00
committed by GitHub
parent 64648ee721 50384ab3c9
commit 2ea7a67106
455 changed files with 20658 additions and 5494 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/reference/commands.md
View File

@@ -71,9 +71,9 @@ Slash commands provide meta-level control over the CLI itself.
[Checkpointing documentation](../cli/checkpointing.md).
- **Equivalent:** `/resume save <tag>`
- **`share [filename]`**
- **Description** Writes the current conversation to a provided Markdown or
- **Description:** Writes the current conversation to a provided Markdown or
JSON file. If no filename is provided, then the CLI will generate one.
- **Usage** `/chat share file.md` or `/chat share file.json`.
- **Usage:** `/chat share file.md` or `/chat share file.json`.
- **Equivalent:** `/resume share [filename]`
### `/clear`
@@ -439,6 +439,12 @@ Slash commands provide meta-level control over the CLI itself.
- **`nodesc`** or **`nodescriptions`**:
- **Description:** Hide tool descriptions, showing only the tool names.
### `/upgrade`
- **Description:** Open the Gemini Code Assist upgrade page in your browser.
This lets you upgrade your tier for higher usage limits.
- **Note:** This command is only available when logged in with Google.
### `/vim`
- **Description:** Toggle vim mode on or off. When vim mode is enabled, the

39
docs/reference/configuration.md
View File

@@ -105,7 +105,8 @@ their corresponding top-level category object in your `settings.json` file.
- **`general.defaultApprovalMode`** (enum):
- **Description:** The default approval mode for tool execution. 'default'
prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is
read-only mode. 'yolo' is not supported yet.
read-only mode. YOLO mode (auto-approve all actions) can only be enabled via
command line (--yolo or --approval-mode=yolo).
- **Default:** `"default"`
- **Values:** `"default"`, `"auto_edit"`, `"plan"`
@@ -146,7 +147,7 @@ their corresponding top-level category object in your `settings.json` file.
- **`general.retryFetchErrors`** (boolean):
- **Description:** Retry on "exception TypeError: fetch failed sending
request" errors.
- **Default:** `false`
- **Default:** `true`
- **`general.maxAttempts`** (number):
- **Description:** Maximum number of attempts for requests to the main chat
@@ -297,7 +298,7 @@ their corresponding top-level category object in your `settings.json` file.
- **Default:** `false`
- **`ui.showUserIdentity`** (boolean):
- **Description:** Show the logged-in user's identity (e.g. email) in the UI.
- **Description:** Show the signed-in user's identity (e.g. email) in the UI.
- **Default:** `true`
- **`ui.useAlternateBuffer`** (boolean):
@@ -872,6 +873,11 @@ their corresponding top-level category object in your `settings.json` file.
confirmation dialogs.
- **Default:** `false`
- **`security.autoAddToPolicyByDefault`** (boolean):
- **Description:** When enabled, the "Allow for all future sessions" option
becomes the default choice for low-risk tools in trusted workspaces.
- **Default:** `false`
- **`security.blockGitExtensions`** (boolean):
- **Description:** Blocks installing and loading extensions from Git.
- **Default:** `false`
@@ -998,6 +1004,12 @@ their corresponding top-level category object in your `settings.json` file.
- **Default:** `false`
- **Requires restart:** Yes
- **`experimental.extensionRegistryURI`** (string):
- **Description:** The URI (web URL or local file path) of the extension
registry.
- **Default:** `"https://geminicli.com/extensions.json"`
- **Requires restart:** Yes
- **`experimental.extensionReloading`** (boolean):
- **Description:** Enables extension loading/unloading within the CLI session.
- **Default:** `false`
@@ -1171,13 +1183,20 @@ their corresponding top-level category object in your `settings.json` file.
Configures connections to one or more Model-Context Protocol (MCP) servers for
discovering and using custom tools. Gemini CLI attempts to connect to each
configured MCP server to discover available tools. If multiple MCP servers
expose a tool with the same name, the tool names will be prefixed with the
server alias you defined in the configuration (e.g.,
`serverAlias__actualToolName`) to avoid conflicts. Note that the system might
strip certain schema properties from MCP tool definitions for compatibility. At
least one of `command`, `url`, or `httpUrl` must be provided. If multiple are
specified, the order of precedence is `httpUrl`, then `url`, then `command`.
configured MCP server to discover available tools. Every discovered tool is
prepended with the `mcp_` prefix and its server alias to form a fully qualified
name (FQN) (e.g., `mcp_serverAlias_actualToolName`) to avoid conflicts. Note
that the system might strip certain schema properties from MCP tool definitions
for compatibility. At least one of `command`, `url`, or `httpUrl` must be
provided. If multiple are specified, the order of precedence is `httpUrl`, then
`url`, then `command`.
> **Warning:** Avoid using underscores (`_`) in your server aliases (e.g., use
> `my-server` instead of `my_server`). The underlying policy engine parses Fully
> Qualified Names (`mcp_server_tool`) using the first underscore after the
> `mcp_` prefix. An underscore in your server alias will cause the parser to
> misidentify the server name, which can cause security policies to fail
> silently.
- **`mcpServers.<SERVER_NAME>`** (object): The server parameters for the named
server.

229
docs/reference/keyboard-shortcuts.md
View File

@@ -8,122 +8,173 @@ available combinations.
#### Basic Controls
| Action | Keys |
| --------------------------------------------------------------- | ------------------- |
| Confirm the current selection or choice. | `Enter` |
| Dismiss dialogs or cancel the current focus. | `Esc`<br />`Ctrl+[` |
| Cancel the current request or quit the CLI when input is empty. | `Ctrl+C` |
| Exit the CLI when the input buffer is empty. | `Ctrl+D` |
| 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` |
#### Cursor Movement
| Action | Keys |
| ------------------------------------------- | ------------------------------------------ |
| Move the cursor to the start of the line. | `Ctrl+A`<br />`Home` |
| Move the cursor to the end of the line. | `Ctrl+E`<br />`End` |
| Move the cursor up one line. | `Up` |
| Move the cursor down one line. | `Down` |
| Move the cursor one character to the left. | `Left` |
| Move the cursor one character to the right. | `Right`<br />`Ctrl+F` |
| Move the cursor one word to the left. | `Ctrl+Left`<br />`Alt+Left`<br />`Alt+B` |
| Move the cursor one word to the right. | `Ctrl+Right`<br />`Alt+Right`<br />`Alt+F` |
| 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` |
#### Editing
| Action | Keys |
| ------------------------------------------------ | -------------------------------------------------------- |
| Delete from the cursor to the end of the line. | `Ctrl+K` |
| Delete from the cursor to the start of the line. | `Ctrl+U` |
| Clear all text in the input field. | `Ctrl+C` |
| Delete the previous word. | `Ctrl+Backspace`<br />`Alt+Backspace`<br />`Ctrl+W` |
| Delete the next word. | `Ctrl+Delete`<br />`Alt+Delete`<br />`Alt+D` |
| Delete the character to the left. | `Backspace`<br />`Ctrl+H` |
| Delete the character to the right. | `Delete`<br />`Ctrl+D` |
| Undo the most recent text edit. | `Cmd/Win+Z`<br />`Alt+Z` |
| Redo the most recent undone text edit. | `Ctrl+Shift+Z`<br />`Shift+Cmd/Win+Z`<br />`Alt+Shift+Z` |
| 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` |
#### Scrolling
| Action | Keys |
| ------------------------ | ----------------------------- |
| Scroll content up. | `Shift+Up` |
| Scroll content down. | `Shift+Down` |
| Scroll to the top. | `Ctrl+Home`<br />`Shift+Home` |
| Scroll to the bottom. | `Ctrl+End`<br />`Shift+End` |
| Scroll up by one page. | `Page Up` |
| Scroll down by one page. | `Page Down` |
| 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` |
#### History & Search
| Action | Keys |
| -------------------------------------------- | ------------ |
| Show the previous entry in history. | `Ctrl+P` |
| Show the next entry in history. | `Ctrl+N` |
| Start reverse search through history. | `Ctrl+R` |
| Submit the selected reverse-search match. | `Enter` |
| Accept a suggestion while reverse searching. | `Tab` |
| Browse and rewind previous interactions. | `Double Esc` |
| 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` |
#### Navigation
| Action | Keys |
| -------------------------------------------------- | --------------- |
| Move selection up in lists. | `Up` |
| Move selection down in lists. | `Down` |
| Move up within dialog options. | `Up`<br />`K` |
| Move down within dialog options. | `Down`<br />`J` |
| Move to the next item or question in a dialog. | `Tab` |
| Move to the previous item or question in a dialog. | `Shift+Tab` |
| 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` |
#### Suggestions & Completions
| Action | Keys |
| --------------------------------------- | -------------------- |
| Accept the inline suggestion. | `Tab`<br />`Enter` |
| Move to the previous completion option. | `Up`<br />`Ctrl+P` |
| Move to the next completion option. | `Down`<br />`Ctrl+N` |
| Expand an inline suggestion. | `Right` |
| Collapse an inline suggestion. | `Left` |
| 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` |
#### Text Input
| Action | Keys |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Submit the current prompt. | `Enter` |
| Insert a newline without submitting. | `Ctrl+Enter`<br />`Cmd/Win+Enter`<br />`Alt+Enter`<br />`Shift+Enter`<br />`Ctrl+J` |
| Open the current prompt or the plan in an external editor. | `Ctrl+X` |
| Paste from the clipboard. | `Ctrl+V`<br />`Cmd/Win+V`<br />`Alt+V` |
| 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` |
#### App Controls
| Action | Keys |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Toggle detailed error information. | `F12` |
| Toggle the full TODO list. | `Ctrl+T` |
| Show IDE context details. | `Ctrl+G` |
| Toggle Markdown rendering. | `Alt+M` |
| Toggle copy mode when in alternate buffer mode. | `Ctrl+S` |
| Toggle YOLO (auto-approval) mode for tool calls. | `Ctrl+Y` |
| 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` |
| Expand and collapse blocks of content when not in alternate buffer mode. | `Ctrl+O` |
| Expand or collapse a paste placeholder when cursor is over placeholder. | `Ctrl+O` |
| Toggle current background shell visibility. | `Ctrl+B` |
| Toggle background shell list. | `Ctrl+L` |
| Kill the active background shell. | `Ctrl+K` |
| Confirm selection in background shell list. | `Enter` |
| Dismiss background shell list. | `Esc` |
| Move focus from background shell to Gemini. | `Shift+Tab` |
| Move focus from background shell list to Gemini. | `Tab` |
| Show warning when trying to move focus away from background shell. | `Tab` |
| Show warning when trying to move focus away from shell input. | `Tab` |
| Move focus from Gemini to the active shell. | `Tab` |
| Move focus from the shell back to Gemini. | `Shift+Tab` |
| Clear the terminal screen and redraw the UI. | `Ctrl+L` |
| Restart the application. | `R`<br />`Shift+R` |
| Suspend the CLI and move it to the background. | `Ctrl+Z` |
| 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` |
#### Background Shell Controls
| 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` |
<!-- KEYBINDINGS-AUTOGEN:END -->
## 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`
## Additional context-specific shortcuts
- `Option+B/F/M` (macOS only): Are interpreted as `Cmd+B/F/M` even if your

31
docs/reference/policy-engine.md
View File

@@ -76,9 +76,13 @@ The `toolName` in the rule must match the name of the tool being called.
- **Wildcards**: You can use wildcards to match multiple tools.
- `*`: Matches **any tool** (built-in or MCP).
- `server__*`: Matches any tool from a specific MCP server.
- `*__toolName`: Matches a specific tool name across **all** MCP servers.
- `*__*`: Matches **any tool from any MCP server**.
- `mcp_server_*`: Matches any tool from a specific MCP server.
- `mcp_*_toolName`: Matches a specific tool name across **all** MCP servers.
- `mcp_*`: Matches **any tool from any MCP server**.
> **Recommendation:** While FQN wildcards are supported, the recommended
> approach for MCP tools is to use the `mcpName` field in your TOML rules. See
> [Special syntax for MCP tools](#special-syntax-for-mcp-tools).
#### Arguments pattern
@@ -164,8 +168,8 @@ A rule matches a tool call if all of its conditions are met:
1. **Tool name**: The `toolName` in the rule must match the name of the tool
being called.
- **Wildcards**: You can use wildcards like `*`, `server__*`, or
`*__toolName` to match multiple tools. See [Tool Name](#tool-name) for
- **Wildcards**: You can use wildcards like `*`, `mcp_server_*`, or
`mcp_*_toolName` to match multiple tools. See [Tool Name](#tool-name) for
details.
2. **Arguments pattern**: If `argsPattern` is specified, the tool's arguments
are converted to a stable JSON string, which is then tested against the
@@ -219,8 +223,12 @@ Here is a breakdown of the fields available in a TOML policy rule:
# A unique name for the tool, or an array of names.
toolName = "run_shell_command"
# (Optional) The name of a subagent. If provided, the rule only applies to tool calls
# made by this specific subagent.
subagent = "generalist"
# (Optional) The name of an MCP server. Can be combined with toolName
# to form a composite name like "mcpName__toolName".
# to form a composite FQN internally like "mcp_mcpName_toolName".
mcpName = "my-custom-server"
# (Optional) Metadata hints provided by the tool. A rule matches if all
@@ -297,7 +305,16 @@ priority = 100
### Special syntax for MCP tools
You can create rules that target tools from Model Context Protocol (MCP) servers
using the `mcpName` field or composite wildcard patterns.
using the `mcpName` field. **This is the recommended approach** for defining MCP
policies, as it is much more robust than manually writing Fully Qualified Names
(FQNs) or string wildcards.
> **Warning:** Do not use underscores (`_`) in your MCP server names (e.g., use
> `my-server` rather than `my_server`). The policy parser splits Fully Qualified
> Names (`mcp_server_tool`) on the _first_ underscore following the `mcp_`
> prefix. If your server name contains an underscore, the parser will
> misinterpret the server identity, which can cause wildcard rules and security
> policies to fail silently.
**1. Targeting a specific tool on a server**