From b15c8550b39c3363089606cfaaf98ddfca8d469c Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 25 Mar 2026 16:00:40 -0500 Subject: [PATCH 1/6] docs: add vi mode shortcuts and clarify MCP sandbox setup --- README.md | 23 +++++++++ docs/cli/sandbox.md | 4 +- docs/reference/configuration.md | 4 ++ docs/reference/keyboard-shortcuts.md | 77 ++++++++++++++++++++++++++++ 4 files changed, 107 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03a7be12968..5e5556b3df4 100644 --- a/README.md +++ b/README.md @@ -344,6 +344,29 @@ custom tools: > @database Run a query to find inactive users ``` +#### Quick start: SQLite + +1. Install an MCP server: `npm install -g @modelcontextprotocol/server-sqlite` +2. Add it to `~/.gemini/settings.json`: + + ```json + { + "mcpServers": { + "sqlite": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sqlite", + "--db", + "/path/to/your.db" + ] + } + } + } + ``` + +3. Use it in the CLI: `> @sqlite show tables` + See the [MCP Server Integration guide](./docs/tools/mcp-server.md) for setup instructions. diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md index e27587abf00..e2354fa4c00 100644 --- a/docs/cli/sandbox.md +++ b/docs/cli/sandbox.md @@ -257,7 +257,9 @@ $env:SANDBOX_SET_UID_GID="false" # Disable UID/GID mapping **Missing commands** -- Add to custom Dockerfile. +- Add to a custom Dockerfile. Automatic `BUILD_SANDBOX` builds are only + available when running Gemini CLI from source; npm installs need a prebuilt + image instead. - Install via `sandbox.bashrc`. **Network issues** diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 5c4ef255440..befbd374711 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -2371,6 +2371,10 @@ sandbox image: BUILD_SANDBOX=1 gemini -s ``` +Building a custom sandbox with `BUILD_SANDBOX` is only supported when running +Gemini CLI from source. If you installed the CLI with npm, build the Docker +image separately and reference that image in your sandbox configuration. + ## Usage statistics To help us improve the Gemini CLI, we collect anonymized usage statistics. This diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md index 2ca7a6bb392..c0e311ec6c3 100644 --- a/docs/reference/keyboard-shortcuts.md +++ b/docs/reference/keyboard-shortcuts.md @@ -235,6 +235,83 @@ a `key` combination. - `Double-click` on a paste placeholder (alternate buffer mode only): Expand to view full content inline. Double-click again to collapse. +## Vi mode shortcuts + +When vim mode is enabled with `/vim` or `general.vimMode: true`, Gemini CLI +supports NORMAL and INSERT modes. + +### Mode switching + +| Action | Keys | +| -------------------------------------------- | --------- | +| Enter NORMAL mode from INSERT mode | `Esc` | +| Enter INSERT mode at the cursor | `i` | +| Enter INSERT mode after the cursor | `a` | +| Enter INSERT mode at the start of the line | `I` | +| Enter INSERT mode at the end of the line | `A` | +| Insert a new line below and switch to INSERT | `o` | +| Insert a new line above and switch to INSERT | `O` | +| Clear input in NORMAL mode | `Esc Esc` | + +### Navigation in NORMAL mode + +| Action | Keys | +| --------------------------------- | --------------- | +| Move left | `h` | +| Move down | `j` | +| Move up | `k` | +| Move right | `l` | +| Move to start of line | `0` | +| Move to first non-whitespace char | `^` | +| Move to end of line | `$` | +| Move forward by word | `w` | +| Move backward by word | `b` | +| Move to end of word | `e` | +| Move forward by WORD | `W` | +| Move backward by WORD | `B` | +| Move to end of WORD | `E` | +| Go to first line | `gg` | +| Go to last line | `G` | +| Go to line N | `N G` or `N gg` | + +Counts are supported for navigation commands. For example, `5j` moves down five +lines and `3w` moves forward three words. + +### Editing in NORMAL mode + +| Action | Keys | +| ------------------------------ | ----- | +| Delete character under cursor | `x` | +| Delete to end of line | `D` | +| Delete line | `dd` | +| Change to end of line | `C` | +| Change line | `cc` | +| Delete forward word | `dw` | +| Delete backward word | `db` | +| Delete to end of word | `de` | +| Delete forward WORD | `dW` | +| Delete backward WORD | `dB` | +| Delete to end of WORD | `dE` | +| Change forward word | `cw` | +| Change backward word | `cb` | +| Change to end of word | `ce` | +| Change forward WORD | `cW` | +| Change backward WORD | `cB` | +| Change to end of WORD | `cE` | +| Delete to start of line | `d0` | +| Delete to first non-whitespace | `d^` | +| Change to start of line | `c0` | +| Change to first non-whitespace | `c^` | +| Delete from first line to here | `dgg` | +| Delete from here to last line | `dG` | +| Change from first line to here | `cgg` | +| Change from here to last line | `cG` | +| Undo last change | `u` | +| Repeat last command | `.` | + +Counts are also supported for editing commands. For example, `3dd` deletes three +lines and `2cw` changes two words. + ## Limitations - On [Windows Terminal](https://en.wikipedia.org/wiki/Windows_Terminal): From 7e60d3d0aa63ef3610a1676064d5e855401909b7 Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 25 Mar 2026 22:22:11 -0500 Subject: [PATCH 2/6] docs: refresh SQLite MCP quick start --- README.md | 14 +++++++------- docs/reference/keyboard-shortcuts.md | 23 +++++++++++++++++++++++ 2 files changed, 30 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5e5556b3df4..ecd21cfcfd6 100644 --- a/README.md +++ b/README.md @@ -346,18 +346,18 @@ custom tools: #### Quick start: SQLite -1. Install an MCP server: `npm install -g @modelcontextprotocol/server-sqlite` -2. Add it to `~/.gemini/settings.json`: +1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) so + you can run Python MCP servers with `uvx`. +2. Add the SQLite reference server to `~/.gemini/settings.json`: ```json { "mcpServers": { "sqlite": { - "command": "npx", + "command": "uvx", "args": [ - "-y", - "@modelcontextprotocol/server-sqlite", - "--db", + "mcp-server-sqlite", + "--db-path", "/path/to/your.db" ] } @@ -365,7 +365,7 @@ custom tools: } ``` -3. Use it in the CLI: `> @sqlite show tables` +3. Use it in the CLI: `> @sqlite list the tables in this database` See the [MCP Server Integration guide](./docs/tools/mcp-server.md) for setup instructions. diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md index c0e311ec6c3..73c1c975da8 100644 --- a/docs/reference/keyboard-shortcuts.md +++ b/docs/reference/keyboard-shortcuts.md @@ -312,6 +312,29 @@ lines and `3w` moves forward three words. Counts are also supported for editing commands. For example, `3dd` deletes three lines and `2cw` changes two words. +### Find, replace, yank, and paste in NORMAL mode + +| Action | Keys | +| ----------------------------------------- | ------------- | +| Find next matching character | `f{char}` | +| Find previous matching character | `F{char}` | +| Move until before next matching character | `t{char}` | +| Move until after previous matching char | `T{char}` | +| Repeat latest character find | `;` | +| Repeat latest character find in reverse | `,` | +| Delete character before cursor | `X` | +| Toggle case under cursor | `~` | +| Replace character under cursor | `r{char}` | +| Yank line | `yy` | +| Yank to end of line | `Y` or `y$` | +| Yank word / WORD | `yw`, `yW` | +| Yank to end of word / WORD | `ye`, `yE` | +| Paste after cursor | `p` | +| Paste before cursor | `P` | + +Delete and change operators also compose with character-find motions, so +commands such as `dfx`, `dtx`, `cFx`, and `cTx` are supported. + ## Limitations - On [Windows Terminal](https://en.wikipedia.org/wiki/Windows_Terminal): From 2feff9587634692b53daf0220cd4d85ea1c4a8b3 Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 25 Mar 2026 22:40:15 -0500 Subject: [PATCH 3/6] docs: clarify vim insert position and SQLite path note --- README.md | 3 +++ docs/reference/keyboard-shortcuts.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ecd21cfcfd6..bffcfafa659 100644 --- a/README.md +++ b/README.md @@ -367,6 +367,9 @@ custom tools: 3. Use it in the CLI: `> @sqlite list the tables in this database` +Use a database path for your platform, such as `/path/to/your.db` on macOS or +Linux, or `C:\\path\\to\\your.db` on Windows. + See the [MCP Server Integration guide](./docs/tools/mcp-server.md) for setup instructions. diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md index 73c1c975da8..8c51a0eb881 100644 --- a/docs/reference/keyboard-shortcuts.md +++ b/docs/reference/keyboard-shortcuts.md @@ -247,7 +247,7 @@ supports NORMAL and INSERT modes. | Enter NORMAL mode from INSERT mode | `Esc` | | Enter INSERT mode at the cursor | `i` | | Enter INSERT mode after the cursor | `a` | -| Enter INSERT mode at the start of the line | `I` | +| Enter INSERT mode at the first non-whitespace character | `I` | | Enter INSERT mode at the end of the line | `A` | | Insert a new line below and switch to INSERT | `o` | | Insert a new line above and switch to INSERT | `O` | From 3cc1d329758f83bda95375095a7aeba87a679eab Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 25 Mar 2026 23:09:31 -0500 Subject: [PATCH 4/6] docs: apply prettier formatting --- README.md | 6 +--- docs/reference/keyboard-shortcuts.md | 54 ++++++++++++++-------------- 2 files changed, 28 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index bffcfafa659..76774cf66de 100644 --- a/README.md +++ b/README.md @@ -355,11 +355,7 @@ custom tools: "mcpServers": { "sqlite": { "command": "uvx", - "args": [ - "mcp-server-sqlite", - "--db-path", - "/path/to/your.db" - ] + "args": ["mcp-server-sqlite", "--db-path", "/path/to/your.db"] } } } diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md index 8c51a0eb881..25f5e8b1c7e 100644 --- a/docs/reference/keyboard-shortcuts.md +++ b/docs/reference/keyboard-shortcuts.md @@ -242,16 +242,16 @@ supports NORMAL and INSERT modes. ### Mode switching -| Action | Keys | -| -------------------------------------------- | --------- | -| Enter NORMAL mode from INSERT mode | `Esc` | -| Enter INSERT mode at the cursor | `i` | -| Enter INSERT mode after the cursor | `a` | -| Enter INSERT mode at the first non-whitespace character | `I` | -| Enter INSERT mode at the end of the line | `A` | -| Insert a new line below and switch to INSERT | `o` | -| Insert a new line above and switch to INSERT | `O` | -| Clear input in NORMAL mode | `Esc Esc` | +| Action | Keys | +| ------------------------------------------------------- | --------- | +| Enter NORMAL mode from INSERT mode | `Esc` | +| Enter INSERT mode at the cursor | `i` | +| Enter INSERT mode after the cursor | `a` | +| Enter INSERT mode at the first non-whitespace character | `I` | +| Enter INSERT mode at the end of the line | `A` | +| Insert a new line below and switch to INSERT | `o` | +| Insert a new line above and switch to INSERT | `O` | +| Clear input in NORMAL mode | `Esc Esc` | ### Navigation in NORMAL mode @@ -314,23 +314,23 @@ lines and `2cw` changes two words. ### Find, replace, yank, and paste in NORMAL mode -| Action | Keys | -| ----------------------------------------- | ------------- | -| Find next matching character | `f{char}` | -| Find previous matching character | `F{char}` | -| Move until before next matching character | `t{char}` | -| Move until after previous matching char | `T{char}` | -| Repeat latest character find | `;` | -| Repeat latest character find in reverse | `,` | -| Delete character before cursor | `X` | -| Toggle case under cursor | `~` | -| Replace character under cursor | `r{char}` | -| Yank line | `yy` | -| Yank to end of line | `Y` or `y$` | -| Yank word / WORD | `yw`, `yW` | -| Yank to end of word / WORD | `ye`, `yE` | -| Paste after cursor | `p` | -| Paste before cursor | `P` | +| Action | Keys | +| ----------------------------------------- | ----------- | +| Find next matching character | `f{char}` | +| Find previous matching character | `F{char}` | +| Move until before next matching character | `t{char}` | +| Move until after previous matching char | `T{char}` | +| Repeat latest character find | `;` | +| Repeat latest character find in reverse | `,` | +| Delete character before cursor | `X` | +| Toggle case under cursor | `~` | +| Replace character under cursor | `r{char}` | +| Yank line | `yy` | +| Yank to end of line | `Y` or `y$` | +| Yank word / WORD | `yw`, `yW` | +| Yank to end of word / WORD | `ye`, `yE` | +| Paste after cursor | `p` | +| Paste before cursor | `P` | Delete and change operators also compose with character-find motions, so commands such as `dfx`, `dtx`, `cFx`, and `cTx` are supported. From a8b74770c0aec70427fba106e96830b3621bdd6a Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 15 Apr 2026 00:14:25 -0500 Subject: [PATCH 5/6] chore: trigger pr update From 95805accad0711c6bc9b0b8aa230a772591498e2 Mon Sep 17 00:00:00 2001 From: Christopher Thomas Date: Wed, 15 Apr 2026 13:42:48 -0500 Subject: [PATCH 6/6] docs: document GOOGLE_GEMINI_BASE_URL and GOOGLE_VERTEX_BASE_URL --- docs/reference/configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index befbd374711..1c0ecd90468 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -2009,6 +2009,21 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. - When set, overrides the default API version used by the SDK. - Example: `export GOOGLE_GENAI_API_VERSION="v1"` (Windows PowerShell: `$env:GOOGLE_GENAI_API_VERSION="v1"`) +- **`GOOGLE_GEMINI_BASE_URL`**: + - Overrides the default base URL for Gemini API requests (when using + `gemini-api-key` authentication). + - Must be a valid URL. For security, it must use HTTPS unless pointing to + `localhost` (or `127.0.0.1` / `[::1]`). + - Example: `export GOOGLE_GEMINI_BASE_URL="https://my-proxy.com"` (Windows + PowerShell: `$env:GOOGLE_GEMINI_BASE_URL="https://my-proxy.com"`) +- **`GOOGLE_VERTEX_BASE_URL`**: + - Overrides the default base URL for Vertex AI API requests (when using + `vertex-ai` authentication). + - Must be a valid URL. For security, it must use HTTPS unless pointing to + `localhost` (or `127.0.0.1` / `[::1]`). + - Example: `export GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com"` + (Windows PowerShell: + `$env:GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com"`) - **`OTLP_GOOGLE_CLOUD_PROJECT`**: - Your Google Cloud Project ID for Telemetry in Google Cloud - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` (Windows