mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-05-12 21:03:05 -07:00
Docs: Refresh docs to organize and standardize reference materials. (#18403)
This commit is contained in:
Jenna Inouye
@@ -1,3 +0,0 @@
|
||||
# Authentication setup
|
||||
|
||||
See: [Getting Started - Authentication Setup](../get-started/authentication.md).
|
||||
@@ -2,9 +2,8 @@
|
||||
|
||||
The Gemini CLI includes a Checkpointing feature that automatically saves a
|
||||
snapshot of your project's state before any file modifications are made by
|
||||
AI-powered tools. This allows you to safely experiment with and apply code
|
||||
changes, knowing you can instantly revert back to the state before the tool was
|
||||
run.
|
||||
AI-powered tools. This lets you safely experiment with and apply code changes,
|
||||
knowing you can instantly revert back to the state before the tool was run.
|
||||
|
||||
## How it works
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# CLI cheatsheet
|
||||
# Gemini CLI cheatsheet
|
||||
|
||||
This page provides a reference for commonly used Gemini CLI commands, options,
|
||||
and parameters.
|
||||
@@ -9,8 +9,7 @@ and parameters.
|
||||
| ---------------------------------- | ---------------------------------- | --------------------------------------------------- |
|
||||
| `gemini` | Start interactive REPL | `gemini` |
|
||||
| `gemini "query"` | Query non-interactively, then exit | `gemini "explain this project"` |
|
||||
| `gemini -p "query"` | Query via SDK, then exit | `gemini -p "explain this function"` |
|
||||
| `cat file \| gemini -p "query"` | Process piped content | `cat logs.txt \| gemini -p "explain"` |
|
||||
| `cat file \| gemini` | Process piped content | `cat logs.txt \| gemini` |
|
||||
| `gemini -i "query"` | Execute and continue interactively | `gemini -i "What is the purpose of this project?"` |
|
||||
| `gemini -r "latest"` | Continue most recent session | `gemini -r "latest"` |
|
||||
| `gemini -r "latest" "query"` | Continue session with a new prompt | `gemini -r "latest" "Check for type errors"` |
|
||||
@@ -53,8 +52,8 @@ and parameters.
|
||||
|
||||
## Model selection
|
||||
|
||||
The `--model` (or `-m`) flag allows you to specify which Gemini model to use.
|
||||
You can use either model aliases (user-friendly names) or concrete model names.
|
||||
The `--model` (or `-m`) flag lets you specify which Gemini model to use. You can
|
||||
use either model aliases (user-friendly names) or concrete model names.
|
||||
|
||||
### Model aliases
|
||||
|
||||
|
||||
+121
-101
@@ -10,22 +10,24 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
|
||||
### Built-in Commands
|
||||
|
||||
- **`/about`**
|
||||
- **Description:** Show version info. Please share this information when
|
||||
filing issues.
|
||||
### `/about`
|
||||
|
||||
- **`/auth`**
|
||||
- **Description:** Open a dialog that lets you change the authentication
|
||||
method.
|
||||
- **Description:** Show version info. Share this information when filing issues.
|
||||
|
||||
### `/auth`
|
||||
|
||||
- **Description:** Open a dialog that lets you change the authentication method.
|
||||
|
||||
### `/bug`
|
||||
|
||||
- **`/bug`**
|
||||
- **Description:** File an issue about Gemini CLI. By default, the issue is
|
||||
filed within the GitHub repository for Gemini CLI. The string you enter
|
||||
after `/bug` will become the headline for the bug being filed. The default
|
||||
`/bug` behavior can be modified using the `advanced.bugCommand` setting in
|
||||
your `.gemini/settings.json` files.
|
||||
filed within the GitHub repository for Gemini CLI. The string you enter after
|
||||
`/bug` will become the headline for the bug being filed. The default `/bug`
|
||||
behavior can be modified using the `advanced.bugCommand` setting in your
|
||||
`.gemini/settings.json` files.
|
||||
|
||||
### `/chat`
|
||||
|
||||
- **`/chat`**
|
||||
- **Description:** Save and resume conversation history for branching
|
||||
conversation state interactively, or resuming a previous state from a later
|
||||
session.
|
||||
@@ -34,9 +36,9 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **Description:** Deletes a saved conversation checkpoint.
|
||||
- **`list`**
|
||||
- **Description:** Lists available tags for chat state resumption.
|
||||
- **Note:** This command only lists chats saved within the current
|
||||
project. Because chat history is project-scoped, chats saved in other
|
||||
project directories will not be displayed.
|
||||
- **Note:** This command only lists chats saved within the current project.
|
||||
Because chat history is project-scoped, chats saved in other project
|
||||
directories will not be displayed.
|
||||
- **`resume <tag>`**
|
||||
- **Description:** Resumes a conversation from a previous save.
|
||||
- **Note:** You can only resume chats that were saved within the current
|
||||
@@ -50,32 +52,33 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- Linux/macOS: `~/.gemini/tmp/<project_hash>/`
|
||||
- Windows: `C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\`
|
||||
- **Behavior:** Chats are saved into a project-specific directory,
|
||||
determined by where you run the CLI. Consequently, saved chats are
|
||||
only accessible when working within that same project.
|
||||
determined by where you run the CLI. Consequently, saved chats are only
|
||||
accessible when working within that same project.
|
||||
- **Note:** These checkpoints are for manually saving and resuming
|
||||
conversation states. For automatic checkpoints created before file
|
||||
modifications, see the
|
||||
[Checkpointing documentation](../cli/checkpointing.md).
|
||||
- **`share [filename]`**
|
||||
- **Description** Writes the current conversation to a provided Markdown
|
||||
or JSON file. If no filename is provided, then the CLI will generate
|
||||
one.
|
||||
- **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`.
|
||||
|
||||
- **`/clear`**
|
||||
### `/clear`
|
||||
|
||||
- **Description:** Clear the terminal screen, including the visible session
|
||||
history and scrollback within the CLI. The underlying session data (for
|
||||
history recall) might be preserved depending on the exact implementation,
|
||||
but the visual display is cleared.
|
||||
- **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear
|
||||
action.
|
||||
history recall) might be preserved depending on the exact implementation, but
|
||||
the visual display is cleared.
|
||||
- **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action.
|
||||
|
||||
- **`/compress`**
|
||||
- **Description:** Replace the entire chat context with a summary. This saves
|
||||
on tokens used for future tasks while retaining a high level summary of what
|
||||
has happened.
|
||||
### `/compress`
|
||||
|
||||
- **Description:** Replace the entire chat context with a summary. This saves on
|
||||
tokens used for future tasks while retaining a high level summary of what has
|
||||
happened.
|
||||
|
||||
### `/copy`
|
||||
|
||||
- **`/copy`**
|
||||
- **Description:** Copies the last output produced by Gemini CLI to your
|
||||
clipboard, for easy sharing or reuse.
|
||||
- **Behavior:**
|
||||
@@ -88,7 +91,8 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- On macOS, it requires `pbcopy`, and on Windows, it requires `clip`. These
|
||||
tools are typically pre-installed on their respective systems.
|
||||
|
||||
- **`/directory`** (or **`/dir`**)
|
||||
### `/directory` (or `/dir`)
|
||||
|
||||
- **Description:** Manage workspace directories for multi-directory support.
|
||||
- **Sub-commands:**
|
||||
- **`add`**:
|
||||
@@ -96,34 +100,33 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
absolute or relative to the current working directory. Moreover, the
|
||||
reference from home directory is supported as well.
|
||||
- **Usage:** `/directory add <path1>,<path2>`
|
||||
- **Note:** Disabled in restrictive sandbox profiles. If you're using
|
||||
that, use `--include-directories` when starting the session instead.
|
||||
- **Note:** Disabled in restrictive sandbox profiles. If you're using that,
|
||||
use `--include-directories` when starting the session instead.
|
||||
- **`show`**:
|
||||
- **Description:** Display all directories added by `/directory add` and
|
||||
`--include-directories`.
|
||||
- **Usage:** `/directory show`
|
||||
|
||||
- **`/docs`**
|
||||
### `/docs`
|
||||
|
||||
- **Description:** Open the Gemini CLI documentation in your browser.
|
||||
|
||||
- **`/editor`**
|
||||
### `/editor`
|
||||
|
||||
- **Description:** Open a dialog for selecting supported editors.
|
||||
|
||||
- **`/extensions`**
|
||||
### `/extensions`
|
||||
|
||||
- **Description:** Lists all active extensions in the current Gemini CLI
|
||||
session. See [Gemini CLI Extensions](../extensions/index.md).
|
||||
|
||||
- **`/help`**
|
||||
### `/help` (or `/?`)
|
||||
|
||||
- **Description:** Display help information about Gemini CLI, including
|
||||
available commands and their usage.
|
||||
|
||||
- **`/shortcuts`**
|
||||
- **Description:** Toggle the shortcuts panel above the input.
|
||||
- **Shortcut:** Press `?` when the prompt is empty.
|
||||
- **Note:** This is separate from the clean UI detail toggle on double-`Tab`,
|
||||
which switches between minimal and full UI chrome.
|
||||
### `/hooks`
|
||||
|
||||
- **`/hooks`**
|
||||
- **Description:** Manage hooks, which allow you to intercept and customize
|
||||
Gemini CLI behavior at specific lifecycle events.
|
||||
- **Sub-commands:**
|
||||
@@ -138,7 +141,8 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **`list`** (or `show`, `panel`):
|
||||
- **Description:** Display all registered hooks with their status.
|
||||
|
||||
- **`/ide`**
|
||||
### `/ide`
|
||||
|
||||
- **Description:** Manage IDE integration.
|
||||
- **Sub-commands:**
|
||||
- **`disable`**:
|
||||
@@ -150,18 +154,15 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **`status`**:
|
||||
- **Description:** Check status of IDE integration.
|
||||
|
||||
- **`/init`**
|
||||
- **Description:** To help users easily create a `GEMINI.md` file, this
|
||||
command analyzes the current directory and generates a tailored context
|
||||
file, making it simpler for them to provide project-specific instructions to
|
||||
the Gemini agent.
|
||||
### `/init`
|
||||
|
||||
- **`/introspect`**
|
||||
- **Description:** Provide debugging information about the current Gemini CLI
|
||||
session, including the state of loaded sub-agents and active hooks. This
|
||||
command is primarily for advanced users and developers.
|
||||
- **Description:** To help users easily create a `GEMINI.md` file, this command
|
||||
analyzes the current directory and generates a tailored context file, making
|
||||
it simpler for them to provide project-specific instructions to the Gemini
|
||||
agent.
|
||||
|
||||
### `/mcp`
|
||||
|
||||
- **`/mcp`**
|
||||
- **Description:** Manage configured Model Context Protocol (MCP) servers.
|
||||
- **Sub-commands:**
|
||||
- **`auth`**:
|
||||
@@ -171,19 +172,19 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
for that server. If no server name is provided, it lists all configured
|
||||
servers that support OAuth authentication.
|
||||
- **`desc`**
|
||||
- **Description:** List configured MCP servers and tools with
|
||||
descriptions.
|
||||
- **Description:** List configured MCP servers and tools with descriptions.
|
||||
- **`list`** or **`ls`**:
|
||||
- **Description:** List configured MCP servers and tools. This is the
|
||||
default action if no subcommand is specified.
|
||||
- **`refresh`**:
|
||||
- **Description:** Restarts all MCP servers and re-discovers their
|
||||
available tools.
|
||||
- **Description:** Restarts all MCP servers and re-discovers their available
|
||||
tools.
|
||||
- **`schema`**:
|
||||
- **Description:** List configured MCP servers and tools with descriptions
|
||||
and schemas.
|
||||
|
||||
- **`/memory`**
|
||||
### `/memory`
|
||||
|
||||
- **Description:** Manage the AI's instructional context (hierarchical memory
|
||||
loaded from `GEMINI.md` files).
|
||||
- **Sub-commands:**
|
||||
@@ -200,47 +201,57 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
with the latest `GEMINI.md` content.
|
||||
- **`show`**:
|
||||
- **Description:** Display the full, concatenated content of the current
|
||||
hierarchical memory that has been loaded from all `GEMINI.md` files.
|
||||
This lets you inspect the instructional context being provided to the
|
||||
Gemini model.
|
||||
hierarchical memory that has been loaded from all `GEMINI.md` files. This
|
||||
lets you inspect the instructional context being provided to the Gemini
|
||||
model.
|
||||
- **Note:** For more details on how `GEMINI.md` files contribute to
|
||||
hierarchical memory, see the
|
||||
[CLI Configuration documentation](../get-started/configuration.md).
|
||||
|
||||
- [**`/model`**](./model.md)
|
||||
### `/model`
|
||||
|
||||
- **Description:** Opens a dialog to choose your Gemini model.
|
||||
|
||||
- **`/policies`**
|
||||
### `/policies`
|
||||
|
||||
- **Description:** Manage policies.
|
||||
- **Sub-commands:**
|
||||
- **`list`**:
|
||||
- **Description:** List all active policies grouped by mode.
|
||||
|
||||
- **`/privacy`**
|
||||
- **Description:** Display the Privacy Notice and allow users to select
|
||||
whether they consent to the collection of their data for service improvement
|
||||
purposes.
|
||||
### `/privacy`
|
||||
|
||||
- **Description:** Display the Privacy Notice and allow users to select whether
|
||||
they consent to the collection of their data for service improvement purposes.
|
||||
|
||||
### `/quit` (or `/exit`)
|
||||
|
||||
- **`/quit`** (or **`/exit`**)
|
||||
- **Description:** Exit Gemini CLI.
|
||||
|
||||
- **`/restore`**
|
||||
### `/restore`
|
||||
|
||||
- **Description:** Restores the project files to the state they were in just
|
||||
before a tool was executed. This is particularly useful for undoing file
|
||||
edits made by a tool. If run without a tool call ID, it will list available
|
||||
before a tool was executed. This is particularly useful for undoing file edits
|
||||
made by a tool. If run without a tool call ID, it will list available
|
||||
checkpoints to restore from.
|
||||
- **Usage:** `/restore [tool_call_id]`
|
||||
- **Note:** Only available if checkpointing is configured via
|
||||
[settings](../get-started/configuration.md). See
|
||||
[Checkpointing documentation](../cli/checkpointing.md) for more details.
|
||||
|
||||
- [**`/rewind`**](./rewind.md)
|
||||
- **Description:** Navigates backward through the conversation history,
|
||||
allowing you to review past interactions and potentially revert to a
|
||||
previous state. This feature helps in managing complex or branched
|
||||
conversations.
|
||||
### `/rewind`
|
||||
|
||||
- **Description:** Navigates backward through the conversation history, letting
|
||||
you review past interactions and potentially revert both chat state and file
|
||||
changes.
|
||||
- **Usage:** Press **Esc** twice as a shortcut.
|
||||
- **Features:**
|
||||
- **Select Interaction:** Preview user prompts and file changes.
|
||||
- **Action Selection:** Choose to rewind history only, revert code changes
|
||||
only, or both.
|
||||
|
||||
### `/resume`
|
||||
|
||||
- **`/resume`**
|
||||
- **Description:** Browse and resume previous conversation sessions. Opens an
|
||||
interactive session browser where you can search, filter, and select from
|
||||
automatically saved conversations.
|
||||
@@ -256,28 +267,32 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
saving required. See [Session Management](../cli/session-management.md) for
|
||||
complete details.
|
||||
|
||||
- [**`/settings`**](./settings.md)
|
||||
### `/settings`
|
||||
|
||||
- **Description:** Open the settings editor to view and modify Gemini CLI
|
||||
settings.
|
||||
- **Details:** This command provides a user-friendly interface for changing
|
||||
settings that control the behavior and appearance of Gemini CLI. It is
|
||||
equivalent to manually editing the `.gemini/settings.json` file, but with
|
||||
validation and guidance to prevent errors. See the
|
||||
[settings documentation](./settings.md) for a full list of available
|
||||
settings.
|
||||
[settings documentation](./settings.md) for a full list of available settings.
|
||||
- **Usage:** Simply run `/settings` and the editor will open. You can then
|
||||
browse or search for specific settings, view their current values, and
|
||||
modify them as desired. Changes to some settings are applied immediately,
|
||||
while others require a restart.
|
||||
browse or search for specific settings, view their current values, and modify
|
||||
them as desired. Changes to some settings are applied immediately, while
|
||||
others require a restart.
|
||||
|
||||
### `/shells` (or `/bashes`)
|
||||
|
||||
- **`/shells`** (or **`/bashes`**)
|
||||
- **Description:** Toggle the background shells view. This allows you to view
|
||||
and manage long-running processes that you've sent to the background.
|
||||
- **`/setup-github`**
|
||||
|
||||
### `/setup-github`
|
||||
|
||||
- **Description:** Set up GitHub Actions to triage issues and review PRs with
|
||||
Gemini.
|
||||
|
||||
- [**`/skills`**](./skills.md)
|
||||
### `/skills`
|
||||
|
||||
- **Description:** Manage Agent Skills, which provide on-demand expertise and
|
||||
specialized workflows.
|
||||
- **Sub-commands:**
|
||||
@@ -294,22 +309,26 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **Description:** Refresh the list of discovered skills from all tiers
|
||||
(workspace, user, and extensions).
|
||||
|
||||
- **`/stats`**
|
||||
### `/stats`
|
||||
|
||||
- **Description:** Display detailed statistics for the current Gemini CLI
|
||||
session, including token usage, cached token savings (when available), and
|
||||
session duration. Note: Cached token information is only displayed when
|
||||
cached tokens are being used, which occurs with API key authentication but
|
||||
not with OAuth authentication at this time.
|
||||
session duration. Note: Cached token information is only displayed when cached
|
||||
tokens are being used, which occurs with API key authentication but not with
|
||||
OAuth authentication at this time.
|
||||
|
||||
- **`/terminal-setup`**
|
||||
- **Description:** Configure terminal keybindings for multiline input (VS
|
||||
Code, Cursor, Windsurf).
|
||||
### `/terminal-setup`
|
||||
|
||||
- [**`/theme`**](./themes.md)
|
||||
- **Description:** Open a dialog that lets you change the visual theme of
|
||||
Gemini CLI.
|
||||
- **Description:** Configure terminal keybindings for multiline input (VS Code,
|
||||
Cursor, Windsurf).
|
||||
|
||||
### `/theme`
|
||||
|
||||
- **Description:** Open a dialog that lets you change the visual theme of Gemini
|
||||
CLI.
|
||||
|
||||
### `/tools`
|
||||
|
||||
- [**`/tools`**](../tools/index.md)
|
||||
- **Description:** Display a list of tools that are currently available within
|
||||
Gemini CLI.
|
||||
- **Usage:** `/tools [desc]`
|
||||
@@ -320,7 +339,8 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **`nodesc`** or **`nodescriptions`**:
|
||||
- **Description:** Hide tool descriptions, showing only the tool names.
|
||||
|
||||
- **`/vim`**
|
||||
### `/vim`
|
||||
|
||||
- **Description:** Toggle vim mode on or off. When vim mode is enabled, the
|
||||
input area supports vim-style navigation and editing commands in both NORMAL
|
||||
and INSERT modes.
|
||||
@@ -330,8 +350,8 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
`a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw`
|
||||
- **INSERT mode:** Standard text input with escape to return to NORMAL mode
|
||||
- **NORMAL mode:** Navigate with `h`, `j`, `k`, `l`; jump by words with `w`,
|
||||
`b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines
|
||||
with `G` (or `gg` for first line)
|
||||
`b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines with
|
||||
`G` (or `gg` for first line)
|
||||
- **Persistent setting:** Vim mode preference is saved to
|
||||
`~/.gemini/settings.json` and restored between sessions
|
||||
- **Repeat last command:** Use `.` to repeat the last editing operation
|
||||
|
||||
+19
-11
@@ -19,18 +19,18 @@ order:
|
||||
- **Location:** `~/.gemini/GEMINI.md` (in your user home directory).
|
||||
- **Scope:** Provides default instructions for all your projects.
|
||||
|
||||
2. **Project root and ancestor context files:**
|
||||
- **Location:** The CLI searches for a `GEMINI.md` file in your current
|
||||
working directory and then in each parent directory up to the project root
|
||||
(identified by a `.git` folder).
|
||||
- **Scope:** Provides context relevant to the entire project.
|
||||
2. **Environment and workspace context files:**
|
||||
- **Location:** The CLI searches for `GEMINI.md` files in your configured
|
||||
workspace directories and their parent directories.
|
||||
- **Scope:** Provides context relevant to the projects you are currently
|
||||
working on.
|
||||
|
||||
3. **Sub-directory context files:**
|
||||
- **Location:** The CLI also scans for `GEMINI.md` files in subdirectories
|
||||
below your current working directory. It respects rules in `.gitignore`
|
||||
and `.geminiignore`.
|
||||
- **Scope:** Lets you write highly specific instructions for a particular
|
||||
component or module.
|
||||
3. **Just-in-time (JIT) context files:**
|
||||
- **Location:** When a tool accesses a file or directory, the CLI
|
||||
automatically scans for `GEMINI.md` files in that directory and its
|
||||
ancestors up to a trusted root.
|
||||
- **Scope:** Lets the model discover highly specific instructions for
|
||||
particular components only when they are needed.
|
||||
|
||||
The CLI footer displays the number of loaded context files, which gives you a
|
||||
quick visual cue of the active instructional context.
|
||||
@@ -106,3 +106,11 @@ While `GEMINI.md` is the default filename, you can configure this in your
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn about [Ignoring files](./gemini-ignore.md) to exclude content from the
|
||||
context system.
|
||||
- Explore the [Memory tool](../tools/memory.md) to save persistent memories.
|
||||
- See how to use [Custom commands](./custom-commands.md) to automate common
|
||||
prompts.
|
||||
|
||||
+34
-372
@@ -1,388 +1,50 @@
|
||||
# Headless mode
|
||||
# Headless mode reference
|
||||
|
||||
Headless mode allows you to run Gemini CLI programmatically from command line
|
||||
scripts and automation tools without any interactive UI. This is ideal for
|
||||
scripting, automation, CI/CD pipelines, and building AI-powered tools.
|
||||
Headless mode provides a programmatic interface to Gemini CLI, returning
|
||||
structured text or JSON output without an interactive terminal UI.
|
||||
|
||||
- [Headless Mode](#headless-mode)
|
||||
- [Overview](#overview)
|
||||
- [Basic Usage](#basic-usage)
|
||||
- [Direct Prompts](#direct-prompts)
|
||||
- [Stdin Input](#stdin-input)
|
||||
- [Combining with File Input](#combining-with-file-input)
|
||||
- [Output Formats](#output-formats)
|
||||
- [Text Output (Default)](#text-output-default)
|
||||
- [JSON Output](#json-output)
|
||||
- [Response Schema](#response-schema)
|
||||
- [Example Usage](#example-usage)
|
||||
- [Streaming JSON Output](#streaming-json-output)
|
||||
- [When to Use Streaming JSON](#when-to-use-streaming-json)
|
||||
- [Event Types](#event-types)
|
||||
- [Basic Usage](#basic-usage)
|
||||
- [Example Output](#example-output)
|
||||
- [Processing Stream Events](#processing-stream-events)
|
||||
- [Real-World Examples](#real-world-examples)
|
||||
- [File Redirection](#file-redirection)
|
||||
- [Configuration Options](#configuration-options)
|
||||
- [Examples](#examples)
|
||||
- [Code review](#code-review)
|
||||
- [Generate commit messages](#generate-commit-messages)
|
||||
- [API documentation](#api-documentation)
|
||||
- [Batch code analysis](#batch-code-analysis)
|
||||
- [Code review](#code-review-1)
|
||||
- [Log analysis](#log-analysis)
|
||||
- [Release notes generation](#release-notes-generation)
|
||||
- [Model and tool usage tracking](#model-and-tool-usage-tracking)
|
||||
- [Resources](#resources)
|
||||
## Technical reference
|
||||
|
||||
## Overview
|
||||
Headless mode is triggered when the CLI is run in a non-TTY environment or when
|
||||
providing a query as a positional argument without the interactive flag.
|
||||
|
||||
The headless mode provides a headless interface to Gemini CLI that:
|
||||
### Output formats
|
||||
|
||||
- Accepts prompts via command line arguments or stdin
|
||||
- Returns structured output (text or JSON)
|
||||
- Supports file redirection and piping
|
||||
- Enables automation and scripting workflows
|
||||
- Provides consistent exit codes for error handling
|
||||
You can specify the output format using the `--output-format` flag.
|
||||
|
||||
## Basic usage
|
||||
#### JSON output
|
||||
|
||||
### Direct prompts
|
||||
Returns a single JSON object containing the response and usage statistics.
|
||||
|
||||
Use the `--prompt` (or `-p`) flag to run in headless mode:
|
||||
- **Schema:**
|
||||
- `response`: (string) The model's final answer.
|
||||
- `stats`: (object) Token usage and API latency metrics.
|
||||
- `error`: (object, optional) Error details if the request failed.
|
||||
|
||||
```bash
|
||||
gemini --prompt "What is machine learning?"
|
||||
```
|
||||
#### Streaming JSON output
|
||||
|
||||
### Stdin input
|
||||
Returns a stream of newline-delimited JSON (JSONL) events.
|
||||
|
||||
Pipe input to Gemini CLI from your terminal:
|
||||
- **Event types:**
|
||||
- `init`: Session metadata (session ID, model).
|
||||
- `message`: User and assistant message chunks.
|
||||
- `tool_use`: Tool call requests with arguments.
|
||||
- `tool_result`: Output from executed tools.
|
||||
- `error`: Non-fatal warnings and system errors.
|
||||
- `result`: Final outcome with aggregated statistics.
|
||||
|
||||
```bash
|
||||
echo "Explain this code" | gemini
|
||||
```
|
||||
## Exit codes
|
||||
|
||||
### Combining with file input
|
||||
The CLI returns standard exit codes to indicate the result of the headless
|
||||
execution:
|
||||
|
||||
Read from files and process with Gemini:
|
||||
- `0`: Success.
|
||||
- `1`: General error or API failure.
|
||||
- `42`: Input error (invalid prompt or arguments).
|
||||
- `53`: Turn limit exceeded.
|
||||
|
||||
```bash
|
||||
cat README.md | gemini --prompt "Summarize this documentation"
|
||||
```
|
||||
## Next steps
|
||||
|
||||
## Output formats
|
||||
|
||||
### Text output (default)
|
||||
|
||||
Standard human-readable output:
|
||||
|
||||
```bash
|
||||
gemini -p "What is the capital of France?"
|
||||
```
|
||||
|
||||
Response format:
|
||||
|
||||
```
|
||||
The capital of France is Paris.
|
||||
```
|
||||
|
||||
### JSON output
|
||||
|
||||
Returns structured data including response, statistics, and metadata. This
|
||||
format is ideal for programmatic processing and automation scripts.
|
||||
|
||||
#### Response schema
|
||||
|
||||
The JSON output follows this high-level structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"response": "string", // The main AI-generated content answering your prompt
|
||||
"stats": {
|
||||
// Usage metrics and performance data
|
||||
"models": {
|
||||
// Per-model API and token usage statistics
|
||||
"[model-name]": {
|
||||
"api": {
|
||||
/* request counts, errors, latency */
|
||||
},
|
||||
"tokens": {
|
||||
/* prompt, response, cached, total counts */
|
||||
}
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
// Tool execution statistics
|
||||
"totalCalls": "number",
|
||||
"totalSuccess": "number",
|
||||
"totalFail": "number",
|
||||
"totalDurationMs": "number",
|
||||
"totalDecisions": {
|
||||
/* accept, reject, modify, auto_accept counts */
|
||||
},
|
||||
"byName": {
|
||||
/* per-tool detailed stats */
|
||||
}
|
||||
},
|
||||
"files": {
|
||||
// File modification statistics
|
||||
"totalLinesAdded": "number",
|
||||
"totalLinesRemoved": "number"
|
||||
}
|
||||
},
|
||||
"error": {
|
||||
// Present only when an error occurred
|
||||
"type": "string", // Error type (e.g., "ApiError", "AuthError")
|
||||
"message": "string", // Human-readable error description
|
||||
"code": "number" // Optional error code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example usage
|
||||
|
||||
```bash
|
||||
gemini -p "What is the capital of France?" --output-format json
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"response": "The capital of France is Paris.",
|
||||
"stats": {
|
||||
"models": {
|
||||
"gemini-2.5-pro": {
|
||||
"api": {
|
||||
"totalRequests": 2,
|
||||
"totalErrors": 0,
|
||||
"totalLatencyMs": 5053
|
||||
},
|
||||
"tokens": {
|
||||
"prompt": 24939,
|
||||
"candidates": 20,
|
||||
"total": 25113,
|
||||
"cached": 21263,
|
||||
"thoughts": 154,
|
||||
"tool": 0
|
||||
}
|
||||
},
|
||||
"gemini-2.5-flash": {
|
||||
"api": {
|
||||
"totalRequests": 1,
|
||||
"totalErrors": 0,
|
||||
"totalLatencyMs": 1879
|
||||
},
|
||||
"tokens": {
|
||||
"prompt": 8965,
|
||||
"candidates": 10,
|
||||
"total": 9033,
|
||||
"cached": 0,
|
||||
"thoughts": 30,
|
||||
"tool": 28
|
||||
}
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"totalCalls": 1,
|
||||
"totalSuccess": 1,
|
||||
"totalFail": 0,
|
||||
"totalDurationMs": 1881,
|
||||
"totalDecisions": {
|
||||
"accept": 0,
|
||||
"reject": 0,
|
||||
"modify": 0,
|
||||
"auto_accept": 1
|
||||
},
|
||||
"byName": {
|
||||
"google_web_search": {
|
||||
"count": 1,
|
||||
"success": 1,
|
||||
"fail": 0,
|
||||
"durationMs": 1881,
|
||||
"decisions": {
|
||||
"accept": 0,
|
||||
"reject": 0,
|
||||
"modify": 0,
|
||||
"auto_accept": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"files": {
|
||||
"totalLinesAdded": 0,
|
||||
"totalLinesRemoved": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming JSON output
|
||||
|
||||
Returns real-time events as newline-delimited JSON (JSONL). Each significant
|
||||
action (initialization, messages, tool calls, results) emits immediately as it
|
||||
occurs. This format is ideal for monitoring long-running operations, building
|
||||
UIs with live progress, and creating automation pipelines that react to events.
|
||||
|
||||
#### When to use streaming JSON
|
||||
|
||||
Use `--output-format stream-json` when you need:
|
||||
|
||||
- **Real-time progress monitoring** - See tool calls and responses as they
|
||||
happen
|
||||
- **Event-driven automation** - React to specific events (e.g., tool failures)
|
||||
- **Live UI updates** - Build interfaces showing AI agent activity in real-time
|
||||
- **Detailed execution logs** - Capture complete interaction history with
|
||||
timestamps
|
||||
- **Pipeline integration** - Stream events to logging/monitoring systems
|
||||
|
||||
#### Event types
|
||||
|
||||
The streaming format emits 6 event types:
|
||||
|
||||
1. **`init`** - Session starts (includes session_id, model)
|
||||
2. **`message`** - User prompts and assistant responses
|
||||
3. **`tool_use`** - Tool call requests with parameters
|
||||
4. **`tool_result`** - Tool execution results (success/error)
|
||||
5. **`error`** - Non-fatal errors and warnings
|
||||
6. **`result`** - Final session outcome with aggregated stats
|
||||
|
||||
#### Basic usage
|
||||
|
||||
```bash
|
||||
# Stream events to console
|
||||
gemini --output-format stream-json --prompt "What is 2+2?"
|
||||
|
||||
# Save event stream to file
|
||||
gemini --output-format stream-json --prompt "Analyze this code" > events.jsonl
|
||||
|
||||
# Parse with jq
|
||||
gemini --output-format stream-json --prompt "List files" | jq -r '.type'
|
||||
```
|
||||
|
||||
#### Example output
|
||||
|
||||
Each line is a complete JSON event:
|
||||
|
||||
```jsonl
|
||||
{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.0-flash-exp"}
|
||||
{"type":"message","role":"user","content":"List files in current directory","timestamp":"2025-10-10T12:00:01.000Z"}
|
||||
{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"},"timestamp":"2025-10-10T12:00:02.000Z"}
|
||||
{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"2025-10-10T12:00:03.000Z"}
|
||||
{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"2025-10-10T12:00:04.000Z"}
|
||||
{"type":"result","status":"success","stats":{"total_tokens":250,"input_tokens":50,"output_tokens":200,"duration_ms":3000,"tool_calls":1},"timestamp":"2025-10-10T12:00:05.000Z"}
|
||||
```
|
||||
|
||||
### File redirection
|
||||
|
||||
Save output to files or pipe to other commands:
|
||||
|
||||
```bash
|
||||
# Save to file
|
||||
gemini -p "Explain Docker" > docker-explanation.txt
|
||||
gemini -p "Explain Docker" --output-format json > docker-explanation.json
|
||||
|
||||
# Append to file
|
||||
gemini -p "Add more details" >> docker-explanation.txt
|
||||
|
||||
# Pipe to other tools
|
||||
gemini -p "What is Kubernetes?" --output-format json | jq '.response'
|
||||
gemini -p "Explain microservices" | wc -w
|
||||
gemini -p "List programming languages" | grep -i "python"
|
||||
```
|
||||
|
||||
## Configuration options
|
||||
|
||||
Key command-line options for headless usage:
|
||||
|
||||
| Option | Description | Example |
|
||||
| ----------------------- | ---------------------------------- | -------------------------------------------------- |
|
||||
| `--prompt`, `-p` | Run in headless mode | `gemini -p "query"` |
|
||||
| `--output-format` | Specify output format (text, json) | `gemini -p "query" --output-format json` |
|
||||
| `--model`, `-m` | Specify the Gemini model | `gemini -p "query" -m gemini-2.5-flash` |
|
||||
| `--debug`, `-d` | Enable debug mode | `gemini -p "query" --debug` |
|
||||
| `--include-directories` | Include additional directories | `gemini -p "query" --include-directories src,docs` |
|
||||
| `--yolo`, `-y` | Auto-approve all actions | `gemini -p "query" --yolo` |
|
||||
| `--approval-mode` | Set approval mode | `gemini -p "query" --approval-mode auto_edit` |
|
||||
|
||||
For complete details on all available configuration options, settings files, and
|
||||
environment variables, see the
|
||||
[Configuration Guide](../get-started/configuration.md).
|
||||
|
||||
## Examples
|
||||
|
||||
#### Code review
|
||||
|
||||
```bash
|
||||
cat src/auth.py | gemini -p "Review this authentication code for security issues" > security-review.txt
|
||||
```
|
||||
|
||||
#### Generate commit messages
|
||||
|
||||
```bash
|
||||
result=$(git diff --cached | gemini -p "Write a concise commit message for these changes" --output-format json)
|
||||
echo "$result" | jq -r '.response'
|
||||
```
|
||||
|
||||
#### API documentation
|
||||
|
||||
```bash
|
||||
result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec for these routes" --output-format json)
|
||||
echo "$result" | jq -r '.response' > openapi.json
|
||||
```
|
||||
|
||||
#### Batch code analysis
|
||||
|
||||
```bash
|
||||
for file in src/*.py; do
|
||||
echo "Analyzing $file..."
|
||||
result=$(cat "$file" | gemini -p "Find potential bugs and suggest improvements" --output-format json)
|
||||
echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
|
||||
echo "Completed analysis for $(basename "$file")" >> reports/progress.log
|
||||
done
|
||||
```
|
||||
|
||||
#### Code review
|
||||
|
||||
```bash
|
||||
result=$(git diff origin/main...HEAD | gemini -p "Review these changes for bugs, security issues, and code quality" --output-format json)
|
||||
echo "$result" | jq -r '.response' > pr-review.json
|
||||
```
|
||||
|
||||
#### Log analysis
|
||||
|
||||
```bash
|
||||
grep "ERROR" /var/log/app.log | tail -20 | gemini -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
|
||||
```
|
||||
|
||||
#### Release notes generation
|
||||
|
||||
```bash
|
||||
result=$(git log --oneline v1.0.0..HEAD | gemini -p "Generate release notes from these commits" --output-format json)
|
||||
response=$(echo "$result" | jq -r '.response')
|
||||
echo "$response"
|
||||
echo "$response" >> CHANGELOG.md
|
||||
```
|
||||
|
||||
#### Model and tool usage tracking
|
||||
|
||||
```bash
|
||||
result=$(gemini -p "Explain this database schema" --include-directories db --output-format json)
|
||||
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
|
||||
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
|
||||
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
|
||||
tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
|
||||
echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
|
||||
echo "$result" | jq -r '.response' > schema-docs.md
|
||||
echo "Recent usage trends:"
|
||||
tail -5 usage.log
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [CLI Configuration](../get-started/configuration.md) - Complete configuration
|
||||
guide
|
||||
- [Authentication](../get-started/authentication.md) - Setup authentication
|
||||
- [Commands](./commands.md) - Interactive commands reference
|
||||
- [Tutorials](./tutorials.md) - Step-by-step automation guides
|
||||
- Follow the [Automation tutorial](./tutorials/automation.md) for practical
|
||||
scripting examples.
|
||||
- See the [CLI reference](./cli-reference.md) for all available flags.
|
||||
|
||||
+111
-55
@@ -1,67 +1,123 @@
|
||||
# Gemini CLI
|
||||
# Using Gemini CLI
|
||||
|
||||
Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
|
||||
prompts with the Gemini AI model and its associated tools. For a general
|
||||
overview of Gemini CLI, see the [main documentation page](../index.md).
|
||||
Gemini CLI is a terminal-first interface that brings the power of Gemini AI
|
||||
models directly into your development workflow. It lets you interact with AI
|
||||
using your local files, shell environment, and project context, creating a
|
||||
bridge between generative AI and your system tools.
|
||||
|
||||
## Basic features
|
||||
## User guides
|
||||
|
||||
- **[Commands](./commands.md):** A reference for all built-in slash commands
|
||||
- **[Custom commands](./custom-commands.md):** Create your own commands and
|
||||
shortcuts for frequently used prompts.
|
||||
- **[Headless mode](./headless.md):** Use Gemini CLI programmatically for
|
||||
scripting and automation.
|
||||
- **[Model selection](./model.md):** Configure the Gemini AI model used by the
|
||||
CLI.
|
||||
- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
|
||||
and appearance.
|
||||
- **[Themes](./themes.md):** Customizing the CLI's appearance with different
|
||||
themes.
|
||||
- **[Keyboard shortcuts](./keyboard-shortcuts.md):** A reference for all
|
||||
keyboard shortcuts to improve your workflow.
|
||||
- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks.
|
||||
These guides provide step-by-step instructions and practical examples for using
|
||||
Gemini CLI in your daily development workflow.
|
||||
|
||||
## Advanced features
|
||||
- **[Quickstart](../get-started/index.md):** Get up and running with Gemini CLI
|
||||
in minutes.
|
||||
- **[Examples](../get-started/examples.md):** See practical examples of Gemini
|
||||
CLI in action.
|
||||
- **[Get started with skills](./tutorials/skills-getting-started.md):** Learn
|
||||
how to use and manage specialized expertise.
|
||||
- **[File management](./tutorials/file-management.md):** How to include, search,
|
||||
and modify local files.
|
||||
- **[Set up an MCP server](./tutorials/mcp-setup.md):** Configure Model Context
|
||||
Protocol servers for custom tools.
|
||||
- **[Manage context and memory](./tutorials/memory-management.md):** Manage
|
||||
persistent instructions and individual facts.
|
||||
- **[Manage sessions and history](./tutorials/session-management.md):** Resume,
|
||||
manage, and rewind your conversations.
|
||||
- **[Execute shell commands](./tutorials/shell-commands.md):** Execute system
|
||||
commands safely directly from your prompt.
|
||||
- **[Plan tasks with todos](./tutorials/task-planning.md):** Using todos for
|
||||
complex, multi-step agent requests.
|
||||
- **[Web search and fetch](./tutorials/web-tools.md):** Searching and fetching
|
||||
content from the web.
|
||||
|
||||
## Features
|
||||
|
||||
Technical reference documentation for each capability of Gemini CLI.
|
||||
|
||||
- **[/about](../cli/commands.md#about):** Show version info.
|
||||
- **[/auth](../cli/commands.md#auth):** Change authentication method.
|
||||
- **[/bug](../cli/commands.md#bug):** File an issue about Gemini CLI.
|
||||
- **[/chat](../cli/commands.md#chat):** Save and resume conversation history.
|
||||
- **[/clear](../cli/commands.md#clear):** Clear the terminal screen.
|
||||
- **[/compress](../cli/commands.md#compress):** Replace context with a summary.
|
||||
- **[/copy](../cli/commands.md#copy):** Copy output to clipboard.
|
||||
- **[/directory](../cli/commands.md#directory-or-dir):** Manage workspace
|
||||
directories.
|
||||
- **[/docs](../cli/commands.md#docs):** Open documentation in browser.
|
||||
- **[/editor](../cli/commands.md#editor):** Select preferred editor.
|
||||
- **[/extensions](../cli/commands.md#extensions):** List active extensions.
|
||||
- **[/help](../cli/commands.md#help-or):** Display help information.
|
||||
- **[/hooks](../hooks/index.md):** Manage hooks for lifecycle events.
|
||||
- **[/ide](../ide-integration/index.md):** Manage IDE integration.
|
||||
- **[/init](../cli/commands.md#init):** Create a GEMINI.md context file.
|
||||
- **[/mcp](../tools/mcp-server.md):** Manage Model Context Protocol servers.
|
||||
- **[/memory](../cli/commands.md#memory):** Manage instructional context.
|
||||
- **[/model](./model.md):** Choose Gemini model.
|
||||
- **[/policies](../cli/commands.md#policies):** Manage security policies.
|
||||
- **[/privacy](../cli/commands.md#privacy):** Display privacy notice.
|
||||
- **[/quit](../cli/commands.md#quit-or-exit):** Exit Gemini CLI.
|
||||
- **[/restore](../cli/commands.md#restore):** Restore file state.
|
||||
- **[/resume](../cli/commands.md#resume):** Browse and resume sessions.
|
||||
- **[/rewind](./rewind.md):** Navigate backward through history.
|
||||
- **[/settings](./settings.md):** Open settings editor.
|
||||
- **[/setup-github](../cli/commands.md#setup-github):** Set up GitHub Actions.
|
||||
- **[/shells](../cli/commands.md#shells-or-bashes):** Toggle background shells
|
||||
view.
|
||||
- **[/skills](./skills.md):** Manage Agent Skills.
|
||||
- **[/stats](../cli/commands.md#stats):** Display session statistics.
|
||||
- **[/terminal-setup](../cli/commands.md#terminal-setup):** Configure
|
||||
keybindings.
|
||||
- **[/theme](./themes.md):** Change visual theme.
|
||||
- **[/tools](../cli/commands.md#tools):** Display list of available tools.
|
||||
- **[/vim](../cli/commands.md#vim):** Toggle vim mode.
|
||||
- **[Activate skill (tool)](../tools/activate-skill.md):** Internal mechanism
|
||||
for loading expert procedures.
|
||||
- **[Ask user (tool)](../tools/ask-user.md):** Internal dialog system for
|
||||
clarification.
|
||||
- **[Checkpointing](./checkpointing.md):** Automatic session snapshots.
|
||||
- **[File system (tool)](../tools/file-system.md):** Technical details for local
|
||||
file operations.
|
||||
- **[Headless mode](./headless.md):** Programmatic and scripting interface.
|
||||
- **[Internal documentation (tool)](../tools/internal-docs.md):** Technical
|
||||
lookup for CLI features.
|
||||
- **[Memory (tool)](../tools/memory.md):** Storage details for persistent facts.
|
||||
- **[Model routing](./model-routing.md):** Automatic fallback resilience.
|
||||
- **[Plan mode (experimental)](./plan-mode.md):** Use a safe, read-only mode for
|
||||
planning complex changes.
|
||||
- **[Checkpointing](./checkpointing.md):** Automatically save and restore
|
||||
snapshots of your session and files.
|
||||
- **[Enterprise configuration](./enterprise.md):** Deploy and manage Gemini CLI
|
||||
in an enterprise environment.
|
||||
- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
|
||||
containerized environment.
|
||||
- **[Agent Skills](./skills.md):** Extend the CLI with specialized expertise and
|
||||
procedural workflows.
|
||||
- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
|
||||
performance.
|
||||
- **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.
|
||||
- **[Trusted folders](./trusted-folders.md):** A security feature to control
|
||||
which projects can use the full capabilities of the CLI.
|
||||
- **[Ignoring files (.geminiignore)](./gemini-ignore.md):** Exclude specific
|
||||
files and directories from being accessed by tools.
|
||||
- **[Context files (GEMINI.md)](./gemini-md.md):** Provide persistent,
|
||||
hierarchical context to the model.
|
||||
- **[System prompt override](./system-prompt.md):** Replace the built‑in system
|
||||
instructions using `GEMINI_SYSTEM_MD`.
|
||||
- **[Sandboxing](./sandbox.md):** Isolate tool execution.
|
||||
- **[Shell (tool)](../tools/shell.md):** Detailed system execution parameters.
|
||||
- **[Telemetry](./telemetry.md):** Usage and performance metric details.
|
||||
- **[Todo (tool)](../tools/todos.md):** Progress tracking specification.
|
||||
- **[Token caching](./token-caching.md):** Performance optimization.
|
||||
- **[Web fetch (tool)](../tools/web-fetch.md):** URL retrieval and extraction
|
||||
details.
|
||||
- **[Web search (tool)](../tools/web-search.md):** Google Search integration
|
||||
technicals.
|
||||
|
||||
## Non-interactive mode
|
||||
## Configuration
|
||||
|
||||
Gemini CLI can be run in a non-interactive mode, which is useful for scripting
|
||||
and automation. In this mode, you pipe input to the CLI, it executes the
|
||||
command, and then it exits.
|
||||
Settings and customization options for Gemini CLI.
|
||||
|
||||
The following example pipes a command to Gemini CLI from your terminal:
|
||||
- **[Custom commands](./custom-commands.md):** Personalized shortcuts.
|
||||
- **[Enterprise configuration](./enterprise.md):** Professional environment
|
||||
controls.
|
||||
- **[Ignore files (.geminiignore)](./gemini-ignore.md):** Exclusion pattern
|
||||
reference.
|
||||
- **[Model configuration](./generation-settings.md):** Fine-tune generation
|
||||
parameters like temperature and thinking budget.
|
||||
- **[Project context (GEMINI.md)](./gemini-md.md):** Technical hierarchy of
|
||||
context files.
|
||||
- **[Settings](./settings.md):** Full `settings.json` schema.
|
||||
- **[System prompt override](./system-prompt.md):** Instruction replacement
|
||||
logic.
|
||||
- **[Themes](./themes.md):** UI personalization technical guide.
|
||||
- **[Trusted folders](./trusted-folders.md):** Security permission logic.
|
||||
|
||||
```bash
|
||||
echo "What is fine tuning?" | gemini
|
||||
```
|
||||
## Next steps
|
||||
|
||||
You can also use the `--prompt` or `-p` flag:
|
||||
|
||||
```bash
|
||||
gemini -p "What is fine tuning?"
|
||||
```
|
||||
|
||||
For comprehensive documentation on headless usage, scripting, automation, and
|
||||
advanced examples, see the **[Headless mode](./headless.md)** guide.
|
||||
- Explore the [Command reference](./commands.md) to learn about all available
|
||||
slash commands.
|
||||
- Read about [Project context](./gemini-md.md) to understand how to provide
|
||||
persistent instructions to the model.
|
||||
- See the [CLI reference](./cli-reference.md) for a quick cheatsheet of flags.
|
||||
|
||||
+11
-11
@@ -1,9 +1,9 @@
|
||||
# Rewind
|
||||
|
||||
The `/rewind` command allows you to go back to a previous state in your
|
||||
conversation and, optionally, revert any file changes made by the AI during
|
||||
those interactions. This is a powerful tool for undoing mistakes, exploring
|
||||
different approaches, or simply cleaning up your session history.
|
||||
The `/rewind` command lets you go back to a previous state in your conversation
|
||||
and, optionally, revert any file changes made by the AI during those
|
||||
interactions. This is a powerful tool for undoing mistakes, exploring different
|
||||
approaches, or simply cleaning up your session history.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -17,13 +17,13 @@ Alternatively, you can use the keyboard shortcut: **Press `Esc` twice**.
|
||||
When you trigger a rewind, an interactive list of your previous interactions
|
||||
appears.
|
||||
|
||||
1. **Select Interaction:** Use the **Up/Down arrow keys** to navigate through
|
||||
1. **Select interaction:** Use the **Up/Down arrow keys** to navigate through
|
||||
the list. The most recent interactions are at the bottom.
|
||||
2. **Preview:** As you select an interaction, you'll see a preview of the user
|
||||
prompt and, if applicable, the number of files changed during that step.
|
||||
3. **Confirm Selection:** Press **Enter** on the interaction you want to rewind
|
||||
3. **Confirm selection:** Press **Enter** on the interaction you want to rewind
|
||||
back to.
|
||||
4. **Action Selection:** After selecting an interaction, you'll be presented
|
||||
4. **Action selection:** After selecting an interaction, you'll be presented
|
||||
with a confirmation dialog with up to three options:
|
||||
- **Rewind conversation and revert code changes:** Reverts both the chat
|
||||
history and the file modifications to the state before the selected
|
||||
@@ -37,14 +37,14 @@ appears.
|
||||
If no code changes were made since the selected point, the options related to
|
||||
reverting code changes will be hidden.
|
||||
|
||||
## Key Considerations
|
||||
## Key considerations
|
||||
|
||||
- **Destructive Action:** Rewinding is a destructive action for your current
|
||||
- **Destructive action:** Rewinding is a destructive action for your current
|
||||
session history and potentially your files. Use it with care.
|
||||
- **Agent Awareness:** When you rewind the conversation, the AI model loses all
|
||||
- **Agent awareness:** When you rewind the conversation, the AI model loses all
|
||||
memory of the interactions that were removed. If you only revert code changes,
|
||||
you may need to inform the model that the files have changed.
|
||||
- **Manual Edits:** Rewinding only affects file changes made by the AI's edit
|
||||
- **Manual edits:** Rewinding only affects file changes made by the AI's edit
|
||||
tools. It does **not** undo manual edits you've made or changes triggered by
|
||||
the shell tool (`!`).
|
||||
- **Compression:** Rewind works across chat compression points by reconstructing
|
||||
|
||||
@@ -1,32 +1,36 @@
|
||||
# Session Management
|
||||
# Session management
|
||||
|
||||
Gemini CLI includes robust session management features that automatically save
|
||||
your conversation history. This allows you to interrupt your work and resume
|
||||
exactly where you left off, review past interactions, and manage your
|
||||
conversation history effectively.
|
||||
Session management saves your conversation history so you can resume your work
|
||||
where you left off. Use these features to review past interactions, manage
|
||||
history across different projects, and configure how long data is retained.
|
||||
|
||||
## Automatic Saving
|
||||
## Automatic saving
|
||||
|
||||
Every time you interact with Gemini CLI, your session is automatically saved.
|
||||
This happens in the background without any manual intervention.
|
||||
Your session history is recorded automatically as you interact with the model.
|
||||
This background process ensures your work is preserved even if you interrupt a
|
||||
session.
|
||||
|
||||
- **What is saved:** The complete conversation history, including:
|
||||
- Your prompts and the model's responses.
|
||||
- All tool executions (inputs and outputs).
|
||||
- Token usage statistics (input/output/cached, etc.).
|
||||
- Assistant thoughts/reasoning summaries (when available).
|
||||
- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`.
|
||||
- Token usage statistics (input, output, cached, etc.).
|
||||
- Assistant thoughts and reasoning summaries (when available).
|
||||
- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`,
|
||||
where `<project_hash>` is a unique identifier based on your project's root
|
||||
directory.
|
||||
- **Scope:** Sessions are project-specific. Switching directories to a different
|
||||
project will switch to that project's session history.
|
||||
project switches to that project's session history.
|
||||
|
||||
## Resuming Sessions
|
||||
## Resuming sessions
|
||||
|
||||
You can resume a previous session to continue the conversation with all prior
|
||||
context restored.
|
||||
context restored. Resuming is supported both through command-line flags and an
|
||||
interactive browser.
|
||||
|
||||
### From the Command Line
|
||||
### From the command line
|
||||
|
||||
When starting the CLI, you can use the `--resume` (or `-r`) flag:
|
||||
When starting Gemini CLI, use the `--resume` (or `-r`) flag to load existing
|
||||
sessions.
|
||||
|
||||
- **Resume latest:**
|
||||
|
||||
@@ -36,8 +40,8 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
|
||||
|
||||
This immediately loads the most recent session.
|
||||
|
||||
- **Resume by index:** First, list available sessions (see
|
||||
[Listing Sessions](#listing-sessions)), then use the index number:
|
||||
- **Resume by index:** List available sessions first (see
|
||||
[Listing sessions](#listing-sessions)), then use the index number:
|
||||
|
||||
```bash
|
||||
gemini --resume 1
|
||||
@@ -48,30 +52,35 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
|
||||
gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
||||
```
|
||||
|
||||
### From the Interactive Interface
|
||||
### From the interactive interface
|
||||
|
||||
While the CLI is running, you can use the `/resume` slash command to open the
|
||||
**Session Browser**:
|
||||
While the CLI is running, use the `/resume` slash command to open the **Session
|
||||
Browser**:
|
||||
|
||||
```text
|
||||
/resume
|
||||
```
|
||||
|
||||
This opens an interactive interface where you can:
|
||||
The Session Browser provides an interactive interface where you can perform the
|
||||
following actions:
|
||||
|
||||
- **Browse:** Scroll through a list of your past sessions.
|
||||
- **Preview:** See details like the session date, message count, and the first
|
||||
user prompt.
|
||||
- **Search:** Press `/` to enter search mode, then type to filter sessions by ID
|
||||
or content.
|
||||
- **Select:** Press `Enter` to resume the selected session.
|
||||
- **Select:** Press **Enter** to resume the selected session.
|
||||
- **Esc:** Press **Esc** to exit the Session Browser.
|
||||
|
||||
## Managing Sessions
|
||||
## Managing sessions
|
||||
|
||||
### Listing Sessions
|
||||
You can list and delete sessions to keep your history organized and manage disk
|
||||
space.
|
||||
|
||||
### Listing sessions
|
||||
|
||||
To see a list of all available sessions for the current project from the command
|
||||
line:
|
||||
line, use the `--list-sessions` flag:
|
||||
|
||||
```bash
|
||||
gemini --list-sessions
|
||||
@@ -87,12 +96,12 @@ Available sessions for this project (3):
|
||||
3. Update documentation (Just now) [abcd1234]
|
||||
```
|
||||
|
||||
### Deleting Sessions
|
||||
### Deleting sessions
|
||||
|
||||
You can remove old or unwanted sessions to free up space or declutter your
|
||||
history.
|
||||
|
||||
**From the Command Line:** Use the `--delete-session` flag with an index or ID:
|
||||
**From the command line:** Use the `--delete-session` flag with an index or ID:
|
||||
|
||||
```bash
|
||||
gemini --delete-session 2
|
||||
@@ -102,17 +111,18 @@ gemini --delete-session 2
|
||||
|
||||
1. Open the browser with `/resume`.
|
||||
2. Navigate to the session you want to remove.
|
||||
3. Press `x`.
|
||||
3. Press **x**.
|
||||
|
||||
## Configuration
|
||||
|
||||
You can configure how Gemini CLI manages your session history in your
|
||||
`settings.json` file.
|
||||
`settings.json` file. These settings let you control retention policies and
|
||||
session lengths.
|
||||
|
||||
### Session Retention
|
||||
### Session retention
|
||||
|
||||
To prevent your history from growing indefinitely, you can enable automatic
|
||||
cleanup policies.
|
||||
To prevent your history from growing indefinitely, enable automatic cleanup
|
||||
policies in your settings.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -126,20 +136,20 @@ cleanup policies.
|
||||
}
|
||||
```
|
||||
|
||||
- **`enabled`**: (boolean) Master switch for session cleanup. Default is
|
||||
- **`enabled`**: (boolean) Master switch for session cleanup. Defaults to
|
||||
`false`.
|
||||
- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w").
|
||||
Sessions older than this will be deleted.
|
||||
- **`maxAge`**: (string) Duration to keep sessions (for example, "24h", "7d",
|
||||
"4w"). Sessions older than this are deleted.
|
||||
- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
|
||||
sessions exceeding this count will be deleted.
|
||||
sessions exceeding this count are deleted.
|
||||
- **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
|
||||
to `"1d"`; sessions newer than this period are never deleted by automatic
|
||||
to `"1d"`. Sessions newer than this period are never deleted by automatic
|
||||
cleanup.
|
||||
|
||||
### Session Limits
|
||||
### Session limits
|
||||
|
||||
You can also limit the length of individual sessions to prevent context windows
|
||||
from becoming too large and expensive.
|
||||
You can limit the length of individual sessions to prevent context windows from
|
||||
becoming too large and expensive.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -149,10 +159,17 @@ from becoming too large and expensive.
|
||||
}
|
||||
```
|
||||
|
||||
- **`maxSessionTurns`**: (number) The maximum number of turns (user + model
|
||||
- **`maxSessionTurns`**: (number) The maximum number of turns (user and model
|
||||
exchanges) allowed in a single session. Set to `-1` for unlimited (default).
|
||||
|
||||
**Behavior when limit is reached:**
|
||||
- **Interactive Mode:** The CLI shows an informational message and stops
|
||||
- **Interactive mode:** The CLI shows an informational message and stops
|
||||
sending requests to the model. You must manually start a new session.
|
||||
- **Non-Interactive Mode:** The CLI exits with an error.
|
||||
- **Non-interactive mode:** The CLI exits with an error.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore the [Memory tool](../tools/memory.md) to save persistent information
|
||||
across sessions.
|
||||
- Learn how to [Checkpoint](./checkpointing.md) your session state.
|
||||
- Check out the [CLI reference](./cli-reference.md) for all command-line flags.
|
||||
|
||||
+2
-2
@@ -46,8 +46,8 @@ remembered across sessions.
|
||||
|
||||
## Custom color themes
|
||||
|
||||
Gemini CLI allows you to create your own custom color themes by specifying them
|
||||
in your `settings.json` file. This gives you full control over the color palette
|
||||
Gemini CLI lets you create your own custom color themes by specifying them in
|
||||
your `settings.json` file. This gives you full control over the color palette
|
||||
used in the CLI.
|
||||
|
||||
### How to define a custom theme
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
# Tutorials
|
||||
|
||||
This page contains tutorials for interacting with Gemini CLI.
|
||||
|
||||
## Agent Skills
|
||||
|
||||
- [Getting Started with Agent Skills](./tutorials/skills-getting-started.md)
|
||||
|
||||
## Setting up a Model Context Protocol (MCP) server
|
||||
|
||||
> [!CAUTION] Before using a third-party MCP server, ensure you trust its source
|
||||
> and understand the tools it provides. Your use of third-party servers is at
|
||||
> your own risk.
|
||||
|
||||
This tutorial demonstrates how to set up an MCP server, using the
|
||||
[GitHub MCP server](https://github.com/github/github-mcp-server) as an example.
|
||||
The GitHub MCP server provides tools for interacting with GitHub repositories,
|
||||
such as creating issues and commenting on pull requests.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following installed and configured:
|
||||
|
||||
- **Docker:** Install and run [Docker].
|
||||
- **GitHub Personal Access Token (PAT):** Create a new [classic] or
|
||||
[fine-grained] PAT with the necessary scopes.
|
||||
|
||||
[Docker]: https://www.docker.com/
|
||||
[classic]: https://github.com/settings/tokens/new
|
||||
[fine-grained]: https://github.com/settings/personal-access-tokens/new
|
||||
|
||||
### Guide
|
||||
|
||||
#### Configure the MCP server in `settings.json`
|
||||
|
||||
In your project's root directory, create or open the
|
||||
[`.gemini/settings.json` file](../get-started/configuration.md). Within the
|
||||
file, add the `mcpServers` configuration block, which provides instructions for
|
||||
how to launch the GitHub MCP server.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Set your GitHub token
|
||||
|
||||
> [!CAUTION] Using a broadly scoped personal access token that has access to
|
||||
> personal and private repositories can lead to information from the private
|
||||
> repository being leaked into the public repository. We recommend using a
|
||||
> fine-grained access token that doesn't share access to both public and private
|
||||
> repositories.
|
||||
|
||||
Use an environment variable to store your GitHub PAT:
|
||||
|
||||
```bash
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN="pat_YourActualGitHubTokenHere"
|
||||
```
|
||||
|
||||
Gemini CLI uses this value in the `mcpServers` configuration that you defined in
|
||||
the `settings.json` file.
|
||||
|
||||
#### Launch Gemini CLI and verify the connection
|
||||
|
||||
When you launch Gemini CLI, it automatically reads your configuration and
|
||||
launches the GitHub MCP server in the background. You can then use natural
|
||||
language prompts to ask Gemini CLI to perform GitHub actions. For example:
|
||||
|
||||
```bash
|
||||
"get all open issues assigned to me in the 'foo/bar' repo and prioritize them"
|
||||
```
|
||||
@@ -0,0 +1,187 @@
|
||||
# Automate tasks with headless mode
|
||||
|
||||
Automate tasks with Gemini CLI. Learn how to use headless mode, pipe data into
|
||||
Gemini CLI, automate workflows with shell scripts, and generate structured JSON
|
||||
output for other applications.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- Familiarity with shell scripting (Bash/Zsh).
|
||||
|
||||
## Why headless mode?
|
||||
|
||||
Headless mode runs Gemini CLI once and exits. It's perfect for:
|
||||
|
||||
- **CI/CD:** Analyzing pull requests automatically.
|
||||
- **Batch processing:** Summarizing a large number of log files.
|
||||
- **Tool building:** Creating your own "AI wrapper" scripts.
|
||||
|
||||
## How to use headless mode
|
||||
|
||||
Run Gemini CLI in headless mode by providing a prompt as a positional argument.
|
||||
This bypasses the interactive chat interface and prints the response to standard
|
||||
output (stdout).
|
||||
|
||||
Run a single command:
|
||||
|
||||
```bash
|
||||
gemini "Write a poem about TypeScript"
|
||||
```
|
||||
|
||||
## How to pipe input to Gemini CLI
|
||||
|
||||
Feed data into Gemini using the standard Unix pipe `|`. Gemini reads the
|
||||
standard input (stdin) as context and answers your question using standard
|
||||
output.
|
||||
|
||||
Pipe a file:
|
||||
|
||||
```bash
|
||||
cat error.log | gemini "Explain why this failed"
|
||||
```
|
||||
|
||||
Pipe a command:
|
||||
|
||||
```bash
|
||||
git diff | gemini "Write a commit message for these changes"
|
||||
```
|
||||
|
||||
## Use Gemini CLI output in scripts
|
||||
|
||||
Because Gemini prints to stdout, you can chain it with other tools or save the
|
||||
results to a file.
|
||||
|
||||
### Scenario: Bulk documentation generator
|
||||
|
||||
You have a folder of Python scripts and want to generate a `README.md` for each
|
||||
one.
|
||||
|
||||
1. Save the following code as `generate_docs.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Loop through all Python files
|
||||
for file in *.py; do
|
||||
echo "Generating docs for $file..."
|
||||
|
||||
# Ask Gemini CLI to generate the documentation and print it to stdout
|
||||
gemini "Generate a Markdown documentation summary for @$file. Print the
|
||||
result to standard output." > "${file%.py}.md"
|
||||
done
|
||||
```
|
||||
|
||||
2. Make the script executable and run it in your directory:
|
||||
|
||||
```bash
|
||||
chmod +x generate_docs.sh
|
||||
./generate_docs.sh
|
||||
```
|
||||
|
||||
This creates a corresponding Markdown file for every Python file in the
|
||||
folder.
|
||||
|
||||
## Extract structured JSON data
|
||||
|
||||
When writing a script, you often need structured data (JSON) to pass to tools
|
||||
like `jq`. To get pure JSON data from the model, combine the
|
||||
`--output-format json` flag with `jq` to parse the response field.
|
||||
|
||||
### Scenario: Extract and return structured data
|
||||
|
||||
1. Save the following script as `generate_json.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Ensure we are in a project root
|
||||
if [ ! -f "package.json" ]; then
|
||||
echo "Error: package.json not found."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Extract data
|
||||
gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json
|
||||
```
|
||||
|
||||
2. Run `generate_json.sh`:
|
||||
|
||||
```bash
|
||||
chmod +x generate_json.sh
|
||||
./generate_json.sh
|
||||
```
|
||||
|
||||
3. Check `data.json`. The file should look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"deps": {
|
||||
"react": "^18.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Build your own custom AI tools
|
||||
|
||||
Use headless mode to perform custom, automated AI tasks.
|
||||
|
||||
### Scenario: Create a "Smart Commit" alias
|
||||
|
||||
You can add a function to your shell configuration (like `.zshrc` or `.bashrc`)
|
||||
to create a `git commit` wrapper that writes the message for you.
|
||||
|
||||
1. Open your `.zshrc` file (or `.bashrc` if you use Bash) in your preferred
|
||||
text editor.
|
||||
|
||||
```bash
|
||||
nano ~/.zshrc
|
||||
```
|
||||
|
||||
**Note**: If you use VS Code, you can run `code ~/.zshrc`.
|
||||
|
||||
2. Scroll to the very bottom of the file and paste this code:
|
||||
|
||||
```bash
|
||||
function gcommit() {
|
||||
# Get the diff of staged changes
|
||||
diff=$(git diff --staged)
|
||||
|
||||
if [ -z "$diff" ]; then
|
||||
echo "No staged changes to commit."
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Ask Gemini to write the message
|
||||
echo "Generating commit message..."
|
||||
msg=$(echo "$diff" | gemini "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
|
||||
|
||||
# Commit with the generated message
|
||||
git commit -m "$msg"
|
||||
}
|
||||
```
|
||||
|
||||
Save your file and exit.
|
||||
|
||||
3. Run this command to make the function available immediately:
|
||||
|
||||
```bash
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
4. Use your new command:
|
||||
|
||||
```bash
|
||||
gcommit
|
||||
```
|
||||
|
||||
Gemini CLI will analyze your staged changes and commit them with a generated
|
||||
message.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore the [Headless mode reference](../../cli/headless.md) for full JSON
|
||||
schema details.
|
||||
- Learn about [Shell commands](shell-commands.md) to let the agent run scripts
|
||||
instead of just writing them.
|
||||
@@ -0,0 +1,142 @@
|
||||
# File management with Gemini CLI
|
||||
|
||||
Explore, analyze, and modify your codebase using Gemini CLI. In this guide,
|
||||
you'll learn how to provide Gemini CLI with files and directories, modify and
|
||||
create files, and control what Gemini CLI can see.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- A project directory to work with (e.g., a git repository).
|
||||
|
||||
## How to give the agent context (Reading files)
|
||||
|
||||
Gemini CLI will generally try to read relevant files, sometimes prompting you
|
||||
for access (depending on your settings). To ensure that Gemini CLI uses a file,
|
||||
you can also include it directly.
|
||||
|
||||
### Direct file inclusion (`@`)
|
||||
|
||||
If you know the path to the file you want to work on, use the `@` symbol. This
|
||||
forces the CLI to read the file immediately and inject its content into your
|
||||
prompt.
|
||||
|
||||
```bash
|
||||
`@src/components/UserProfile.tsx Explain how this component handles user data.`
|
||||
```
|
||||
|
||||
### Working with multiple files
|
||||
|
||||
Complex features often span multiple files. You can chain `@` references to give
|
||||
the agent a complete picture of the dependencies.
|
||||
|
||||
```bash
|
||||
`@src/components/UserProfile.tsx @src/types/User.ts Refactor the component to use the updated User interface.`
|
||||
```
|
||||
|
||||
### Including entire directories
|
||||
|
||||
For broad questions or refactoring, you can include an entire directory. Be
|
||||
careful with large folders, as this consumes more tokens.
|
||||
|
||||
```bash
|
||||
`@src/utils/ Check these utility functions for any deprecated API usage.`
|
||||
```
|
||||
|
||||
## How to find files (Exploration)
|
||||
|
||||
If you _don't_ know the exact file path, you can ask Gemini CLI to find it for
|
||||
you. This is useful when navigating a new codebase or looking for specific
|
||||
logic.
|
||||
|
||||
### Scenario: Find a component definition
|
||||
|
||||
You know there's a `UserProfile` component, but you don't know where it lives.
|
||||
|
||||
```none
|
||||
`Find the file that defines the UserProfile component.`
|
||||
```
|
||||
|
||||
Gemini uses the `glob` or `list_directory` tools to search your project
|
||||
structure. It will return the specific path (e.g.,
|
||||
`src/components/UserProfile.tsx`), which you can then use with `@` in your next
|
||||
turn.
|
||||
|
||||
> **Tip:** You can also ask for lists of files, like "Show me all the TypeScript
|
||||
> configuration files in the root directory."
|
||||
|
||||
## How to modify code
|
||||
|
||||
Once Gemini CLI has context, you can direct it to make specific edits. The agent
|
||||
is capable of complex refactoring, not just simple text replacement.
|
||||
|
||||
```none
|
||||
`Update @src/components/UserProfile.tsx to show a loading spinner if the user data is null.`
|
||||
```
|
||||
|
||||
Gemini CLI uses the `replace` tool to propose a targeted code change.
|
||||
|
||||
### Creating new files
|
||||
|
||||
You can also ask the agent to create entirely new files or folder structures.
|
||||
|
||||
```none
|
||||
`Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.`
|
||||
```
|
||||
|
||||
Gemini CLI uses the `write_file` tool to generate the new file from scratch.
|
||||
|
||||
## Review and confirm changes
|
||||
|
||||
Gemini CLI prioritizes safety. Before any file is modified, it presents a
|
||||
unified diff of the proposed changes.
|
||||
|
||||
```diff
|
||||
- if (!user) return null;
|
||||
+ if (!user) return <LoadingSpinner />;
|
||||
```
|
||||
|
||||
- **Red lines (-):** Code that will be removed.
|
||||
- **Green lines (+):** Code that will be added.
|
||||
|
||||
Press **y** to confirm and apply the change to your local file system. If the
|
||||
diff doesn't look right, press **n** to cancel and refine your prompt.
|
||||
|
||||
## Verify the result
|
||||
|
||||
After the edit is complete, verify the fix. You can simply read the file again
|
||||
or, better yet, run your project's tests.
|
||||
|
||||
```none
|
||||
`Run the tests for the UserProfile component.`
|
||||
```
|
||||
|
||||
Gemini CLI uses the `run_shell_command` tool to execute your test runner (e.g.,
|
||||
`npm test` or `jest`). This ensures the changes didn't break existing
|
||||
functionality.
|
||||
|
||||
## Advanced: Controlling what Gemini sees
|
||||
|
||||
By default, Gemini CLI respects your `.gitignore` file. It won't read or search
|
||||
through `node_modules`, build artifacts, or other ignored paths.
|
||||
|
||||
If you have sensitive files (like `.env`) or large assets that you want to keep
|
||||
hidden from the AI _without_ ignoring them in Git, you can create a
|
||||
`.geminiignore` file in your project root.
|
||||
|
||||
**Example `.geminiignore`:**
|
||||
|
||||
```text
|
||||
.env
|
||||
local-db-dump.sql
|
||||
private-notes.md
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn how to [Manage context and memory](memory-management.md) to keep your
|
||||
agent smarter over long sessions.
|
||||
- See [Execute shell commands](shell-commands.md) for more on running tests and
|
||||
builds.
|
||||
- Explore the technical [File system reference](../../tools/file-system.md) for
|
||||
advanced tool parameters.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Set up an MCP server
|
||||
|
||||
Connect Gemini CLI to your external databases and services. In this guide,
|
||||
you'll learn how to extend Gemini CLI's capabilities by installing the GitHub
|
||||
MCP server and using it to manage your repositories.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed.
|
||||
- **Docker:** Required for this specific example (many MCP servers run as Docker
|
||||
containers).
|
||||
- **GitHub token:** A Personal Access Token (PAT) with repo permissions.
|
||||
|
||||
## How to prepare your credentials
|
||||
|
||||
Most MCP servers require authentication. For GitHub, you need a PAT.
|
||||
|
||||
1. Create a [fine-grained PAT](https://github.com/settings/tokens?type=beta).
|
||||
2. Grant it **Read** access to **Metadata** and **Contents**, and
|
||||
**Read/Write** access to **Issues** and **Pull Requests**.
|
||||
3. Store it in your environment:
|
||||
|
||||
```bash
|
||||
export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."
|
||||
```
|
||||
|
||||
## How to configure Gemini CLI
|
||||
|
||||
You tell Gemini about new servers by editing your `settings.json`.
|
||||
|
||||
1. Open `~/.gemini/settings.json` (or the project-specific
|
||||
`.gemini/settings.json`).
|
||||
2. Add the `mcpServers` block. This tells Gemini: "Run this docker container
|
||||
and talk to it."
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/modelcontextprotocol/servers/github:latest"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** The `command` is `docker`, and the rest are arguments passed to it.
|
||||
> We map the local environment variable into the container so your secret isn't
|
||||
> hardcoded in the config file.
|
||||
|
||||
## How to verify the connection
|
||||
|
||||
Restart Gemini CLI. It will automatically try to start the defined servers.
|
||||
|
||||
**Command:** `/mcp list`
|
||||
|
||||
You should see: `✓ github: docker ... - Connected`
|
||||
|
||||
If you see `Disconnected` or an error, check that Docker is running and your API
|
||||
token is valid.
|
||||
|
||||
## How to use the new tools
|
||||
|
||||
Now that the server is running, the agent has new capabilities ("tools"). You
|
||||
don't need to learn special commands; just ask in natural language.
|
||||
|
||||
### Scenario: Listing pull requests
|
||||
|
||||
**Prompt:** `List the open PRs in the google/gemini-cli repository.`
|
||||
|
||||
The agent will:
|
||||
|
||||
1. Recognize the request matches a GitHub tool.
|
||||
2. Call `github_list_pull_requests`.
|
||||
3. Present the data to you.
|
||||
|
||||
### Scenario: Creating an issue
|
||||
|
||||
**Prompt:**
|
||||
`Create an issue in my repo titled "Bug: Login fails" with the description "See logs".`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Server won't start?** Try running the docker command manually in your
|
||||
terminal to see if it prints an error (e.g., "image not found").
|
||||
- **Tools not found?** Run `/mcp refresh` to force the CLI to re-query the
|
||||
server for its capabilities.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore the [MCP servers reference](../../tools/mcp-server.md) to learn about
|
||||
SSE and HTTP transports for remote servers.
|
||||
- Browse the
|
||||
[official MCP server list](https://github.com/modelcontextprotocol/servers) to
|
||||
find connectors for Slack, Postgres, Google Drive, and more.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Manage context and memory
|
||||
|
||||
Control what Gemini CLI knows about you and your projects. In this guide, you'll
|
||||
learn how to define project-wide rules with `GEMINI.md`, teach the agent
|
||||
persistent facts, and inspect the active context.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- A project directory where you want to enforce specific rules.
|
||||
|
||||
## Why manage context?
|
||||
|
||||
Out of the box, Gemini CLI is smart but generic. It doesn't know your preferred
|
||||
testing framework, your indentation style, or that you hate using `any` in
|
||||
TypeScript. Context management solves this by giving the agent persistent
|
||||
memory.
|
||||
|
||||
You'll use these features when you want to:
|
||||
|
||||
- **Enforce standards:** Ensure every generated file matches your team's style
|
||||
guide.
|
||||
- **Set a persona:** Tell the agent to act as a "Senior Rust Engineer" or "QA
|
||||
Specialist."
|
||||
- **Remember facts:** Save details like "My database port is 5432" so you don't
|
||||
have to repeat them.
|
||||
|
||||
## How to define project-wide rules (GEMINI.md)
|
||||
|
||||
The most powerful way to control the agent's behavior is through `GEMINI.md`
|
||||
files. These are Markdown files containing instructions that are automatically
|
||||
loaded into every conversation.
|
||||
|
||||
### Scenario: Create a project context file
|
||||
|
||||
1. In the root of your project, create a file named `GEMINI.md`.
|
||||
|
||||
2. Add your instructions:
|
||||
|
||||
```markdown
|
||||
# Project Instructions
|
||||
|
||||
- **Framework:** We use React with Vite.
|
||||
- **Styling:** Use Tailwind CSS for all styling. Do not write custom CSS.
|
||||
- **Testing:** All new components must include a Vitest unit test.
|
||||
- **Tone:** Be concise. Don't explain basic React concepts.
|
||||
```
|
||||
|
||||
3. Start a new session. Gemini CLI will now know these rules automatically.
|
||||
|
||||
### Scenario: Using the hierarchy
|
||||
|
||||
Context is loaded hierarchically. This allows you to have general rules for
|
||||
everything and specific rules for sub-projects.
|
||||
|
||||
1. **Global:** `~/.gemini/GEMINI.md` (Rules for _every_ project you work on).
|
||||
2. **Project Root:** `./GEMINI.md` (Rules for the current repository).
|
||||
3. **Subdirectory:** `./src/GEMINI.md` (Rules specific to the `src` folder).
|
||||
|
||||
**Example:** You might set "Always use strict typing" in your global config, but
|
||||
"Use Python 3.11" only in your backend repository.
|
||||
|
||||
## How to teach the agent facts (Memory)
|
||||
|
||||
Sometimes you don't want to write a config file. You just want to tell the agent
|
||||
something once and have it remember forever. You can do this naturally in chat.
|
||||
|
||||
### Scenario: Saving a memory
|
||||
|
||||
Just tell the agent to remember something.
|
||||
|
||||
**Prompt:** `Remember that I prefer using 'const' over 'let' wherever possible.`
|
||||
|
||||
The agent will use the `save_memory` tool to store this fact in your global
|
||||
memory file.
|
||||
|
||||
**Prompt:** `Save the fact that the staging server IP is 10.0.0.5.`
|
||||
|
||||
### Scenario: Using memory in conversation
|
||||
|
||||
Once a fact is saved, you don't need to invoke it explicitly. The agent "knows"
|
||||
it.
|
||||
|
||||
**Next Prompt:** `Write a script to deploy to staging.`
|
||||
|
||||
**Agent Response:** "I'll write a script to deploy to **10.0.0.5**..."
|
||||
|
||||
## How to manage and inspect context
|
||||
|
||||
As your project grows, you might want to see exactly what instructions the agent
|
||||
is following.
|
||||
|
||||
### Scenario: View active context
|
||||
|
||||
To see the full, concatenated set of instructions currently loaded (from all
|
||||
`GEMINI.md` files and saved memories), use the `/memory show` command.
|
||||
|
||||
**Command:** `/memory show`
|
||||
|
||||
This prints the raw text the model receives at the start of the session. It's
|
||||
excellent for debugging why the agent might be ignoring a rule.
|
||||
|
||||
### Scenario: Refresh context
|
||||
|
||||
If you edit a `GEMINI.md` file while a session is running, the agent won't know
|
||||
immediately. Force a reload with:
|
||||
|
||||
**Command:** `/memory refresh`
|
||||
|
||||
## Best practices
|
||||
|
||||
- **Keep it focused:** Don't dump your entire internal wiki into `GEMINI.md`.
|
||||
Keep instructions actionable and relevant to code generation.
|
||||
- **Use negative constraints:** Explicitly telling the agent what _not_ to do
|
||||
(e.g., "Do not use class components") is often more effective than vague
|
||||
positive instructions.
|
||||
- **Review often:** Periodically check your `GEMINI.md` files to remove outdated
|
||||
rules.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn about [Session management](session-management.md) to see how short-term
|
||||
history works.
|
||||
- Explore the [Command reference](../../cli/commands.md) for more `/memory`
|
||||
options.
|
||||
- Read the technical spec for [Project context](../../cli/gemini-md.md).
|
||||
@@ -0,0 +1,105 @@
|
||||
# Manage sessions and history
|
||||
|
||||
Resume, browse, and rewind your conversations with Gemini CLI. In this guide,
|
||||
you'll learn how to switch between tasks, manage your session history, and undo
|
||||
mistakes using the rewind feature.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- At least one active or past session.
|
||||
|
||||
## How to resume where you left off
|
||||
|
||||
It's common to switch context—maybe you're waiting for a build and want to work
|
||||
on a different feature. Gemini makes it easy to jump back in.
|
||||
|
||||
### Scenario: Resume the last session
|
||||
|
||||
The fastest way to pick up your most recent work is with the `--resume` flag (or
|
||||
`-r`).
|
||||
|
||||
```bash
|
||||
gemini -r
|
||||
```
|
||||
|
||||
This restores your chat history and memory, so you can say "Continue with the
|
||||
next step" immediately.
|
||||
|
||||
### Scenario: Browse past sessions
|
||||
|
||||
If you want to find a specific conversation from yesterday, use the interactive
|
||||
browser.
|
||||
|
||||
**Command:** `/resume`
|
||||
|
||||
This opens a searchable list of all your past sessions. You'll see:
|
||||
|
||||
- A timestamp (e.g., "2 hours ago").
|
||||
- The first user message (helping you identify the topic).
|
||||
- The number of turns in the conversation.
|
||||
|
||||
Select a session and press **Enter** to load it.
|
||||
|
||||
## How to manage your workspace
|
||||
|
||||
Over time, you'll accumulate a lot of history. Keeping your session list clean
|
||||
helps you find what you need.
|
||||
|
||||
### Scenario: Deleting sessions
|
||||
|
||||
In the `/resume` browser, navigate to a session you no longer need and press
|
||||
**x**. This permanently deletes the history for that specific conversation.
|
||||
|
||||
You can also manage sessions from the command line:
|
||||
|
||||
```bash
|
||||
# List all sessions with their IDs
|
||||
gemini --list-sessions
|
||||
|
||||
# Delete a specific session by ID or index
|
||||
gemini --delete-session 1
|
||||
```
|
||||
|
||||
## How to rewind time (Undo mistakes)
|
||||
|
||||
Gemini CLI's **Rewind** feature is like `Ctrl+Z` for your workflow.
|
||||
|
||||
### Scenario: Triggering rewind
|
||||
|
||||
At any point in a chat, type `/rewind` or press **Esc** twice.
|
||||
|
||||
### Scenario: Choosing a restore point
|
||||
|
||||
You'll see a list of your recent interactions. Select the point _before_ the
|
||||
undesired changes occurred.
|
||||
|
||||
### Scenario: Choosing what to revert
|
||||
|
||||
Gemini gives you granular control over the undo process. You can choose to:
|
||||
|
||||
1. **Rewind conversation:** Only remove the chat history. The files stay
|
||||
changed. (Useful if the code is good but the chat got off track).
|
||||
2. **Revert code changes:** Keep the chat history but undo the file edits.
|
||||
(Useful if you want to keep the context but retry the implementation).
|
||||
3. **Rewind both:** Restore everything to exactly how it was.
|
||||
|
||||
## How to fork conversations
|
||||
|
||||
Sometimes you want to try two different approaches to the same problem.
|
||||
|
||||
1. Start a session and get to a decision point.
|
||||
2. Save the current state with `/chat save decision-point`.
|
||||
3. Try your first approach.
|
||||
4. Later, use `/chat resume decision-point` to fork the conversation back to
|
||||
that moment and try a different approach.
|
||||
|
||||
This creates a new branch of history without losing your original work.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn about [Checkpointing](../../cli/checkpointing.md) to understand the
|
||||
underlying safety mechanism.
|
||||
- Explore [Task planning](task-planning.md) to keep complex sessions organized.
|
||||
- See the [Command reference](../../cli/commands.md) for all `/chat` and
|
||||
`/resume` options.
|
||||
@@ -0,0 +1,107 @@
|
||||
# Execute shell commands
|
||||
|
||||
Use the CLI to run builds, manage git, and automate system tasks without leaving
|
||||
the conversation. In this guide, you'll learn how to run commands directly,
|
||||
automate complex workflows, and manage background processes safely.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- Basic familiarity with your system's shell (Bash, Zsh, PowerShell, etc.).
|
||||
|
||||
## How to run commands directly (`!`)
|
||||
|
||||
Sometimes you just need to check a file size or git status without asking the AI
|
||||
to do it for you. You can pass commands directly to your shell using the `!`
|
||||
prefix.
|
||||
|
||||
**Example:** `!ls -la`
|
||||
|
||||
This executes `ls -la` immediately and prints the output to your terminal. The
|
||||
AI doesn't "see" this output unless you paste it back into the chat or use it in
|
||||
a prompt.
|
||||
|
||||
### Scenario: Entering Shell mode
|
||||
|
||||
If you're doing a lot of manual work, toggle "Shell Mode" by typing `!` and
|
||||
pressing **Enter**. Now, everything you type is sent to the shell until you exit
|
||||
(usually by pressing **Esc** or typing `exit`).
|
||||
|
||||
## How to automate complex tasks
|
||||
|
||||
You can automate tasks using a combination of Gemini CLI and shell commands.
|
||||
|
||||
### Scenario: Run tests and fix failures
|
||||
|
||||
You want to run tests and fix any failures.
|
||||
|
||||
**Prompt:**
|
||||
`Run the unit tests. If any fail, analyze the error and try to fix the code.`
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Gemini calls `run_shell_command('npm test')`.
|
||||
2. You see a confirmation prompt: `Allow command 'npm test'? [y/N]`.
|
||||
3. You press `y`.
|
||||
4. The tests run. If they fail, Gemini reads the error output.
|
||||
5. Gemini uses `read_file` to inspect the failing test.
|
||||
6. Gemini uses `replace` to fix the bug.
|
||||
7. Gemini runs `npm test` again to verify the fix.
|
||||
|
||||
This loop turns Gemini into an autonomous engineer.
|
||||
|
||||
## How to manage background processes
|
||||
|
||||
You can ask Gemini to start long-running tasks, like development servers or file
|
||||
watchers.
|
||||
|
||||
**Prompt:** `Start the React dev server in the background.`
|
||||
|
||||
Gemini will run the command (e.g., `npm run dev`) and detach it.
|
||||
|
||||
### Scenario: Viewing active shells
|
||||
|
||||
To see what's running in the background, use the `/shells` command.
|
||||
|
||||
**Command:** `/shells`
|
||||
|
||||
This opens a dashboard where you can view logs or kill runaway processes.
|
||||
|
||||
## How to handle interactive commands
|
||||
|
||||
Gemini CLI attempts to handle interactive commands (like `git add -p` or
|
||||
confirmation prompts) by streaming the output to you. However, for highly
|
||||
interactive tools (like `vim` or `top`), it's often better to run them yourself
|
||||
in a separate terminal window or use the `!` prefix.
|
||||
|
||||
## Safety first
|
||||
|
||||
Giving an AI access to your shell is powerful but risky. Gemini CLI includes
|
||||
several safety layers.
|
||||
|
||||
### Confirmation prompts
|
||||
|
||||
By default, **every** shell command requested by the agent requires your
|
||||
explicit approval.
|
||||
|
||||
- **Allow once:** Runs the command one time.
|
||||
- **Allow always:** Trusts this specific command for the rest of the session.
|
||||
- **Deny:** Stops the agent.
|
||||
|
||||
### Sandboxing
|
||||
|
||||
For maximum security, especially when running untrusted code or exploring new
|
||||
projects, we strongly recommend enabling Sandboxing. This runs all shell
|
||||
commands inside a secure Docker container.
|
||||
|
||||
**Enable sandboxing:** Use the `--sandbox` flag when starting the CLI:
|
||||
`gemini --sandbox`.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn about [Sandboxing](../../cli/sandbox.md) to safely run destructive
|
||||
commands.
|
||||
- See the [Shell tool reference](../../tools/shell.md) for configuration options
|
||||
like timeouts and working directories.
|
||||
- Explore [Task planning](task-planning.md) to see how shell commands fit into
|
||||
larger workflows.
|
||||
@@ -1,23 +1,27 @@
|
||||
# Getting Started with Agent Skills
|
||||
# Get started with Agent Skills
|
||||
|
||||
Agent Skills allow you to extend Gemini CLI with specialized expertise. This
|
||||
tutorial will guide you through creating your first skill and using it in a
|
||||
session.
|
||||
Agent Skills extend Gemini CLI with specialized expertise. In this guide, you'll
|
||||
learn how to create your first skill, bundle custom scripts, and activate them
|
||||
during a session.
|
||||
|
||||
## 1. Create your first skill
|
||||
## How to create a skill
|
||||
|
||||
A skill is a directory containing a `SKILL.md` file. Let's create an **API
|
||||
Auditor** skill that helps you verify if local or remote endpoints are
|
||||
A skill is defined by a directory containing a `SKILL.md` file. Let's create an
|
||||
**API Auditor** skill that helps you verify if local or remote endpoints are
|
||||
responding correctly.
|
||||
|
||||
1. **Create the skill directory structure:**
|
||||
### Create the directory structure
|
||||
|
||||
1. Run the following command to create the folders:
|
||||
|
||||
```bash
|
||||
mkdir -p .gemini/skills/api-auditor/scripts
|
||||
```
|
||||
|
||||
2. **Create the `SKILL.md` file:** Create a file at
|
||||
`.gemini/skills/api-auditor/SKILL.md` with the following content:
|
||||
### Create the definition
|
||||
|
||||
1. Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent
|
||||
_when_ to use the skill and _how_ to behave.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -40,9 +44,12 @@ responding correctly.
|
||||
without an `https://` protocol.
|
||||
```
|
||||
|
||||
3. **Create the bundled Node.js script:** Create a file at
|
||||
`.gemini/skills/api-auditor/scripts/audit.js`. This script will be used by
|
||||
the agent to perform the actual check:
|
||||
### Add the tool logic
|
||||
|
||||
Skills can bundle resources like scripts.
|
||||
|
||||
1. Create a file at `.gemini/skills/api-auditor/scripts/audit.js`. This is the
|
||||
code the agent will run.
|
||||
|
||||
```javascript
|
||||
// .gemini/skills/api-auditor/scripts/audit.js
|
||||
@@ -59,39 +66,36 @@ responding correctly.
|
||||
.catch((e) => console.error(`Result: Failed (${e.message})`));
|
||||
```
|
||||
|
||||
## 2. Verify the skill is discovered
|
||||
## How to verify discovery
|
||||
|
||||
Use the `/skills` slash command (or `gemini skills list` from your terminal) to
|
||||
see if Gemini CLI has found your new skill.
|
||||
Gemini CLI automatically discovers skills in the `.gemini/skills` directory.
|
||||
Check that it found your new skill.
|
||||
|
||||
In a Gemini CLI session:
|
||||
|
||||
```
|
||||
/skills list
|
||||
```
|
||||
**Command:** `/skills list`
|
||||
|
||||
You should see `api-auditor` in the list of available skills.
|
||||
|
||||
## 3. Use the skill in a chat
|
||||
## How to use the skill
|
||||
|
||||
Now, let's see the skill in action. Start a new session and ask a question about
|
||||
an endpoint.
|
||||
Now, try it out. Start a new session and ask a question that triggers the
|
||||
skill's description.
|
||||
|
||||
**User:** "Can you audit http://geminili.com"
|
||||
**User:** "Can you audit http://geminicli.com"
|
||||
|
||||
Gemini will recognize the request matches the `api-auditor` description and will
|
||||
ask for your permission to activate it.
|
||||
Gemini recognizes the request matches the `api-auditor` description and asks for
|
||||
permission to activate it.
|
||||
|
||||
**Model:** (After calling `activate_skill`) "I've activated the **api-auditor**
|
||||
skill. I'll run the audit script now..."
|
||||
|
||||
Gemini will then use the `run_shell_command` tool to execute your bundled Node
|
||||
Gemini then uses the `run_shell_command` tool to execute your bundled Node
|
||||
script:
|
||||
|
||||
`node .gemini/skills/api-auditor/scripts/audit.js http://geminili.com`
|
||||
|
||||
## Next Steps
|
||||
## Next steps
|
||||
|
||||
- Explore [Agent Skills Authoring Guide](../skills.md#creating-a-skill) to learn
|
||||
about more advanced skill features.
|
||||
- Explore the
|
||||
[Agent Skills Authoring Guide](../../cli/skills.md#creating-a-skill) to learn
|
||||
about more advanced features.
|
||||
- Learn how to share skills via [Extensions](../../extensions/index.md).
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# Plan tasks with todos
|
||||
|
||||
Keep complex jobs on the rails with Gemini CLI's built-in task planning. In this
|
||||
guide, you'll learn how to ask for a plan, execute it step-by-step, and monitor
|
||||
progress with the todo list.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- A complex task in mind (e.g., a multi-file refactor or new feature).
|
||||
|
||||
## Why use task planning?
|
||||
|
||||
Standard LLMs have a limited context window and can "forget" the original goal
|
||||
after 10 turns of code generation. Task planning provides:
|
||||
|
||||
1. **Visibility:** You see exactly what the agent plans to do _before_ it
|
||||
starts.
|
||||
2. **Focus:** The agent knows exactly which step it's working on right now.
|
||||
3. **Resilience:** If the agent gets stuck, the plan helps it get back on
|
||||
track.
|
||||
|
||||
## How to ask for a plan
|
||||
|
||||
The best way to trigger task planning is to explicitly ask for it.
|
||||
|
||||
**Prompt:**
|
||||
`I want to migrate this project from JavaScript to TypeScript. Please make a plan first.`
|
||||
|
||||
Gemini will analyze your codebase and use the `write_todos` tool to generate a
|
||||
structured list.
|
||||
|
||||
**Example Plan:**
|
||||
|
||||
1. [ ] Create `tsconfig.json`.
|
||||
2. [ ] Rename `.js` files to `.ts`.
|
||||
3. [ ] Fix type errors in `utils.js`.
|
||||
4. [ ] Fix type errors in `server.js`.
|
||||
5. [ ] Verify build passes.
|
||||
|
||||
## How to review and iterate
|
||||
|
||||
Once the plan is generated, it appears in your CLI. Review it.
|
||||
|
||||
- **Missing steps?** Tell the agent: "You forgot to add a step for installing
|
||||
`@types/node`."
|
||||
- **Wrong order?** Tell the agent: "Let's verify the build _after_ each file,
|
||||
not just at the end."
|
||||
|
||||
The agent will update the todo list dynamically.
|
||||
|
||||
## How to execute the plan
|
||||
|
||||
Tell the agent to proceed.
|
||||
|
||||
**Prompt:** `Looks good. Start with the first step.`
|
||||
|
||||
As the agent works, you'll see the todo list update in real-time above the input
|
||||
box.
|
||||
|
||||
- **Current focus:** The active task is highlighted (e.g.,
|
||||
`[IN_PROGRESS] Create tsconfig.json`).
|
||||
- **Progress:** Completed tasks are marked as done.
|
||||
|
||||
## How to monitor progress (`Ctrl+T`)
|
||||
|
||||
For a long-running task, the full todo list might be hidden to save space. You
|
||||
can toggle the full view at any time.
|
||||
|
||||
**Action:** Press **Ctrl+T**.
|
||||
|
||||
This shows the complete list, including pending, in-progress, and completed
|
||||
items. It's a great way to check "how much is left?" without scrolling back up.
|
||||
|
||||
## How to handle unexpected changes
|
||||
|
||||
Plans change. Maybe you discover a library is incompatible halfway through.
|
||||
|
||||
**Prompt:**
|
||||
`Actually, let's skip the 'server.js' refactor for now. It's too risky.`
|
||||
|
||||
The agent will mark that task as `cancelled` or remove it, and move to the next
|
||||
item. This dynamic adjustment is what makes the todo system powerful—it's a
|
||||
living document, not a static text block.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore [Session management](session-management.md) to save your plan and
|
||||
finish it tomorrow.
|
||||
- See the [Todo tool reference](../../tools/todos.md) for technical schema
|
||||
details.
|
||||
- Learn about [Memory management](memory-management.md) to persist planning
|
||||
preferences (e.g., "Always create a test plan first").
|
||||
@@ -0,0 +1,78 @@
|
||||
# Web search and fetch
|
||||
|
||||
Access the live internet directly from your prompt. In this guide, you'll learn
|
||||
how to search for up-to-date documentation, fetch deep context from specific
|
||||
URLs, and apply that knowledge to your code.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- An internet connection.
|
||||
|
||||
## How to research new technologies
|
||||
|
||||
Imagine you want to use a library released yesterday. The model doesn't know
|
||||
about it yet. You need to teach it.
|
||||
|
||||
### Scenario: Find documentation
|
||||
|
||||
**Prompt:**
|
||||
`Search for the 'Bun 1.0' release notes and summarize the key changes.`
|
||||
|
||||
Gemini uses the `google_web_search` tool to find relevant pages and synthesizes
|
||||
an answer. This "grounding" process ensures the agent isn't hallucinating
|
||||
features that don't exist.
|
||||
|
||||
**Prompt:** `Find the documentation for the 'React Router v7' loader API.`
|
||||
|
||||
## How to fetch deep context
|
||||
|
||||
Search gives you a summary, but sometimes you need the raw details. The
|
||||
`web_fetch` tool lets you feed a specific URL directly into the agent's context.
|
||||
|
||||
### Scenario: Reading a blog post
|
||||
|
||||
You found a blog post with the exact solution to your bug.
|
||||
|
||||
**Prompt:**
|
||||
`Read https://example.com/fixing-memory-leaks and explain how to apply it to my code.`
|
||||
|
||||
Gemini will retrieve the page content (stripping away ads and navigation) and
|
||||
use it to answer your question.
|
||||
|
||||
### Scenario: Comparing sources
|
||||
|
||||
You can even fetch multiple pages to compare approaches.
|
||||
|
||||
**Prompt:**
|
||||
`Compare the pagination patterns in https://api.example.com/v1/docs and https://api.example.com/v2/docs.`
|
||||
|
||||
## How to apply knowledge to code
|
||||
|
||||
The real power comes when you combine web tools with file editing.
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Search:** "How do I implement auth with Supabase?"
|
||||
2. **Fetch:** "Read this guide: https://supabase.com/docs/guides/auth."
|
||||
3. **Implement:** "Great. Now use that pattern to create an `auth.ts` file in
|
||||
my project."
|
||||
|
||||
## How to troubleshoot errors
|
||||
|
||||
When you hit an obscure error message, paste it into the chat.
|
||||
|
||||
**Prompt:**
|
||||
`I'm getting 'Error: hydration mismatch' in Next.js. Search for recent solutions.`
|
||||
|
||||
The agent will search sources such as GitHub issues, StackOverflow, and forums
|
||||
to find relevant fixes that might be too new to be in its base training set.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore [File management](file-management.md) to see how to apply the code you
|
||||
generate.
|
||||
- See the [Web search tool reference](../../tools/web-search.md) for citation
|
||||
details.
|
||||
- See the [Web fetch tool reference](../../tools/web-fetch.md) for technical
|
||||
limitations.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Core concepts
|
||||
|
||||
This guide explains the fundamental concepts and terminology used throughout the
|
||||
Gemini CLI ecosystem. Understanding these terms will help you make the most of
|
||||
the tool's capabilities.
|
||||
|
||||
## Approval mode
|
||||
|
||||
**Approval mode** determines the level of autonomy you grant to the agent when
|
||||
executing tools.
|
||||
|
||||
- **Default:** The agent asks for confirmation before performing any potentially
|
||||
impactful action (like writing files or running shell commands).
|
||||
- **Auto-edit:** File modifications are applied automatically, but shell
|
||||
commands still require confirmation.
|
||||
- **YOLO (You Only Look Once):** The agent runs all tools without asking for
|
||||
permission. High risk, high speed.
|
||||
|
||||
## Checkpointing
|
||||
|
||||
**Checkpointing** is a safety feature that automatically snapshots your
|
||||
project's file state before the agent performs any destructive action (like
|
||||
writing a file).
|
||||
|
||||
- **Snapshots:** Stored in a hidden Git repository (separate from your project's
|
||||
Git history).
|
||||
- **Restore:** Allows you to instantly revert changes if the agent makes a
|
||||
mistake, using the `/restore` command.
|
||||
|
||||
## Context
|
||||
|
||||
**Context** refers to the information the agent has about your current task and
|
||||
environment. Gemini CLI provides context through several mechanisms:
|
||||
|
||||
- **Conversation history:** The chat log of the current session.
|
||||
- **Project context (`GEMINI.md`):** Persistent instructions and rules defined
|
||||
in your project's root or subdirectories.
|
||||
- **File content:** Files you explicitly reference (e.g., `@src/app.ts`) or that
|
||||
the agent reads using tools.
|
||||
- **Environment:** Information about your operating system, shell, and working
|
||||
directory.
|
||||
|
||||
Effective context management is key to getting accurate and relevant responses.
|
||||
|
||||
## Extension
|
||||
|
||||
An **Extension** is a pluggable package that adds new capabilities to Gemini
|
||||
CLI. Extensions can bundle:
|
||||
|
||||
- **Skills:** Specialized procedural knowledge.
|
||||
- **MCP Servers:** Connections to external tools and data.
|
||||
- **Commands:** Custom slash commands.
|
||||
|
||||
## Headless mode
|
||||
|
||||
**Headless mode** refers to running Gemini CLI without the interactive terminal
|
||||
UI (TUI). This is used for scripting, automation, and piping data into or out of
|
||||
the agent.
|
||||
|
||||
- **Interactive:** `gemini` (starts the REPL).
|
||||
- **Headless:** `gemini "Fix this file"` (runs once and exits).
|
||||
|
||||
## Hook
|
||||
|
||||
A **Hook** is a script or function that intercepts specific lifecycle events in
|
||||
the CLI.
|
||||
|
||||
- **Use cases:** Logging tool usage, validating user input, or modifying the
|
||||
agent's system prompt dynamically.
|
||||
- **Lifecycle:** Hooks can run before or after the agent starts, before tools
|
||||
are executed, or after the session ends.
|
||||
|
||||
## Model Context Protocol (MCP)
|
||||
|
||||
The **Model Context Protocol (MCP)** is an open standard that allows Gemini CLI
|
||||
to connect to external data sources and tools.
|
||||
|
||||
- **MCP Server:** A lightweight application that exposes resources (data) and
|
||||
tools (functions) to the CLI.
|
||||
- **Use case:** Connecting Gemini to a PostgreSQL database, a GitHub repository,
|
||||
or a Slack workspace without building custom integration logic into the CLI
|
||||
core.
|
||||
|
||||
## Policy engine
|
||||
|
||||
The **Policy Engine** is the security subsystem that enforces rules on tool
|
||||
execution. It evaluates every tool call against your configuration (e.g.,
|
||||
[Trusted folders](#trusted-folders), allowed commands) to decide whether to:
|
||||
|
||||
- Allow the action immediately.
|
||||
- Require user confirmation.
|
||||
- Block the action entirely.
|
||||
|
||||
## Sandboxing
|
||||
|
||||
**Sandboxing** is an optional security mode that isolates the agent's execution
|
||||
environment. When enabled, the agent runs inside a secure container (e.g.,
|
||||
Docker), preventing it from accessing sensitive files or system resources
|
||||
outside of the designated workspace.
|
||||
|
||||
## Session
|
||||
|
||||
A **Session** is a single continuous interaction thread with the agent.
|
||||
|
||||
- **State:** Sessions maintain conversation history and short-term memory.
|
||||
- **Persistence:** Sessions are automatically saved, allowing you to pause,
|
||||
resume, or rewind them later.
|
||||
|
||||
## Skill
|
||||
|
||||
A **Skill** (or **Agent Skill**) is a package of specialized expertise that the
|
||||
agent can load on demand. Unlike general context, a skill provides specific
|
||||
procedural knowledge for a distinct task.
|
||||
|
||||
- **Example:** A "Code Reviewer" skill might contain a checklist of security
|
||||
vulnerabilities to look for and a specific format for reporting findings.
|
||||
- **Activation:** Skills are typically activated dynamically when the agent
|
||||
recognizes a matching request.
|
||||
|
||||
## Tool
|
||||
|
||||
A **Tool** is a specific function or capability that the agent can execute.
|
||||
Tools allow the AI to interact with the outside world.
|
||||
|
||||
- **Built-in tools:** Core capabilities like `read_file`, `run_shell_command`,
|
||||
and `google_web_search`.
|
||||
- **MCP tools:** External tools provided by
|
||||
[MCP servers](#model-context-protocol-mcp).
|
||||
|
||||
When the agent uses a tool, it pauses generation, executes the code, and feeds
|
||||
the output back into its context window.
|
||||
|
||||
## Trusted folders
|
||||
|
||||
**Trusted folders** are specific directories you have explicitly authorized the
|
||||
agent to access without repeated confirmation prompts. This is a key component
|
||||
of the [Policy engine](#policy-engine) to balance security and usability.
|
||||
@@ -1374,10 +1374,9 @@ for that specific session.
|
||||
- Specifies the Gemini model to use for this session.
|
||||
- Example: `npm start -- --model gemini-3-pro-preview`
|
||||
- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
|
||||
- **Deprecated:** Use positional arguments instead.
|
||||
- Used to pass a prompt directly to the command. This invokes Gemini CLI in a
|
||||
non-interactive mode.
|
||||
- For scripting examples, use the `--output-format json` flag to get
|
||||
structured output.
|
||||
- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
|
||||
- Starts an interactive session with the provided prompt as the initial input.
|
||||
- The prompt is processed within the interactive session, not before it.
|
||||
|
||||
+37
-117
@@ -1,13 +1,18 @@
|
||||
# Gemini CLI examples
|
||||
|
||||
Not sure where to get started with Gemini CLI? This document covers examples on
|
||||
how to use Gemini CLI for a variety of tasks.
|
||||
Gemini CLI helps you automate common engineering tasks by combining AI reasoning
|
||||
with local system tools. This document provides examples of how to use the CLI
|
||||
for file management, code analysis, and data transformation.
|
||||
|
||||
**Note:** Results are examples intended to showcase potential use cases. Your
|
||||
results may vary.
|
||||
> **Note:** These examples demonstrate potential capabilities. Your actual
|
||||
> results can vary based on the model used and your project environment.
|
||||
|
||||
## Rename your photographs based on content
|
||||
|
||||
You can use Gemini CLI to automate file management tasks that require visual
|
||||
analysis. In this example, Gemini CLI renames images based on their actual
|
||||
subject matter.
|
||||
|
||||
Scenario: You have a folder containing the following files:
|
||||
|
||||
```bash
|
||||
@@ -22,9 +27,9 @@ Give Gemini the following prompt:
|
||||
Rename the photos in my "photos" directory based on their contents.
|
||||
```
|
||||
|
||||
Result: Gemini will ask for permission to rename your files.
|
||||
Result: Gemini asks for permission to rename your files.
|
||||
|
||||
Select **Allow once** and your files will be renamed:
|
||||
Select **Allow once** and your files are renamed:
|
||||
|
||||
```bash
|
||||
photos/yellow_flowers.png
|
||||
@@ -34,6 +39,9 @@ photos/green_android_robot.png
|
||||
|
||||
## Explain a repository by reading its code
|
||||
|
||||
Gemini CLI is effective for rapid codebase exploration. The following example
|
||||
shows how to ask Gemini CLI to fetch, analyze, and summarize a remote project.
|
||||
|
||||
Scenario: You want to understand how a popular open-source utility works by
|
||||
inspecting its code, not just its README.
|
||||
|
||||
@@ -43,15 +51,14 @@ Give Gemini CLI the following prompt:
|
||||
Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
|
||||
```
|
||||
|
||||
Result: Gemini will perform a sequence of actions to answer your request.
|
||||
Result: Gemini performs a sequence of actions to answer your request.
|
||||
|
||||
1. First, it will ask for permission to run `git clone` to download the
|
||||
repository.
|
||||
2. Next, it will find the important source files and ask for permission to read
|
||||
1. First, it asks for permission to run `git clone` to download the repository.
|
||||
2. Next, it finds the important source files and asks for permission to read
|
||||
them.
|
||||
3. Finally, after analyzing the code, it will provide a summary.
|
||||
3. Finally, after analyzing the code, it provides a summary.
|
||||
|
||||
Gemini CLI will return an explanation based on the actual source code:
|
||||
Gemini CLI returns an explanation based on the actual source code:
|
||||
|
||||
```markdown
|
||||
The `chalk` library is a popular npm package for styling terminal output with
|
||||
@@ -74,25 +81,11 @@ colors. After analyzing the source code, here's how it works:
|
||||
|
||||
## Combine two spreadsheets into one spreadsheet
|
||||
|
||||
Gemini CLI can process and transform data across multiple files. Use this
|
||||
capability to merge reports or reformat data sets without manual copying.
|
||||
|
||||
Scenario: You have two .csv files: `Revenue - 2023.csv` and
|
||||
`Revenue - 2024.csv`. Each file contains monthly revenue figures, like so:
|
||||
|
||||
```csv
|
||||
January,0
|
||||
February,0
|
||||
March,0
|
||||
April,900
|
||||
May,1000
|
||||
June,1000
|
||||
July,1200
|
||||
August,1800
|
||||
September,2000
|
||||
October,2400
|
||||
November,3400
|
||||
December,2100
|
||||
```
|
||||
|
||||
You want to combine these two .csv files into a single .csv file.
|
||||
`Revenue - 2024.csv`. Each file contains monthly revenue figures.
|
||||
|
||||
Give Gemini CLI the following prompt:
|
||||
|
||||
@@ -100,9 +93,8 @@ Give Gemini CLI the following prompt:
|
||||
Combine the two .csv files into a single .csv file, with each year a different column.
|
||||
```
|
||||
|
||||
Result: Gemini CLI will read each file and then ask for permission to write a
|
||||
new file. Provide your permission and Gemini CLI will provide the following
|
||||
.csv:
|
||||
Result: Gemini CLI reads each file and then asks for permission to write a new
|
||||
file. Provide your permission and Gemini CLI provides the combined data:
|
||||
|
||||
```csv
|
||||
Month,2023,2024
|
||||
@@ -122,6 +114,10 @@ December,2100,9000
|
||||
|
||||
## Run unit tests
|
||||
|
||||
Gemini CLI can generate boilerplate code and tests based on your existing
|
||||
implementation. This example demonstrates how to request code coverage for a
|
||||
JavaScript component.
|
||||
|
||||
Scenario: You've written a simple login page. You wish to write unit tests to
|
||||
ensure that your login page has code coverage.
|
||||
|
||||
@@ -131,89 +127,13 @@ Give Gemini CLI the following prompt:
|
||||
Write unit tests for Login.js.
|
||||
```
|
||||
|
||||
Result: Gemini CLI will ask for permission to write a new file and create a test
|
||||
for your login page
|
||||
Result: Gemini CLI asks for permission to write a new file and creates a test
|
||||
for your login page.
|
||||
|
||||
```javascript
|
||||
import React from 'react';
|
||||
import { render, fireEvent, waitFor } from '@testing-library/react';
|
||||
import Login from './Login';
|
||||
## Next steps
|
||||
|
||||
// Mock the API call for login
|
||||
jest.mock('./api', () => ({
|
||||
login: jest.fn(),
|
||||
}));
|
||||
|
||||
describe('Login component', () => {
|
||||
it('renders the login form correctly', () => {
|
||||
const { getByLabelText, getByText } = render(<Login />);
|
||||
|
||||
expect(getByLabelText('Username')).toBeInTheDocument();
|
||||
expect(getByLabelText('Password')).toBeInTheDocument();
|
||||
expect(getByText('Login')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('shows an error message with invalid credentials', async () => {
|
||||
const { getByLabelText, getByText, findByText } = render(<Login />);
|
||||
const usernameInput = getByLabelText('Username');
|
||||
const passwordInput = getByLabelText('Password');
|
||||
const loginButton = getByText('Login');
|
||||
|
||||
// Mock the API to return an error
|
||||
require('./api').login.mockRejectedValue(new Error('Invalid credentials'));
|
||||
|
||||
fireEvent.change(usernameInput, { target: { value: 'testuser' } });
|
||||
fireEvent.change(passwordInput, { target: { value: 'wrongpassword' } });
|
||||
fireEvent.click(loginButton);
|
||||
|
||||
const errorMessage = await findByText('Invalid credentials');
|
||||
expect(errorMessage).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('logs in successfully with valid credentials', async () => {
|
||||
const onLoginSuccess = jest.fn();
|
||||
const { getByLabelText, getByText } = render(
|
||||
<Login onLoginSuccess={onLoginSuccess} />,
|
||||
);
|
||||
const usernameInput = getByLabelText('Username');
|
||||
const passwordInput = getByLabelText('Password');
|
||||
const loginButton = getByText('Login');
|
||||
|
||||
// Mock the API to return a success message
|
||||
require('./api').login.mockResolvedValue({ success: true });
|
||||
|
||||
fireEvent.change(usernameInput, { target: { value: 'testuser' } });
|
||||
fireEvent.change(passwordInput, { target: { value: 'correctpassword' } });
|
||||
fireEvent.click(loginButton);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(onLoginSuccess).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
it('disables the submit button while submitting', async () => {
|
||||
const { getByLabelText, getByText } = render(<Login />);
|
||||
const usernameInput = getByLabelText('Username');
|
||||
const passwordInput = getByLabelText('Password');
|
||||
const loginButton = getByText('Login');
|
||||
|
||||
// Mock the API to have a delay
|
||||
require('./api').login.mockImplementation(
|
||||
() =>
|
||||
new Promise((resolve) =>
|
||||
setTimeout(() => resolve({ success: true }), 1000),
|
||||
),
|
||||
);
|
||||
|
||||
fireEvent.change(usernameInput, { target: { value: 'testuser' } });
|
||||
fireEvent.change(passwordInput, { target: { value: 'correctpassword' } });
|
||||
fireEvent.click(loginButton);
|
||||
|
||||
expect(loginButton).toBeDisabled();
|
||||
|
||||
await waitFor(() => {
|
||||
expect(loginButton).not.toBeDisabled();
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
- Explore the [User guides](../cli/index.md#user-guides) for detailed
|
||||
walkthroughs of common tasks.
|
||||
- Follow the [Quickstart](./index.md) to start your first session.
|
||||
- See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of
|
||||
available commands.
|
||||
|
||||
@@ -64,8 +64,10 @@ and more.
|
||||
|
||||
To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md).
|
||||
|
||||
## What's next?
|
||||
## Next steps
|
||||
|
||||
- Find out more about [Gemini CLI's tools](../tools/index.md).
|
||||
- Review [Gemini CLI's commands](../cli/commands.md).
|
||||
- Learn how to [get started with Gemini 3](./gemini-3.md).
|
||||
- Follow the [File management](../cli/tutorials/file-management.md) guide to
|
||||
start working with your codebase.
|
||||
- See [Shell commands](../cli/tutorials/shell-commands.md) to learn about
|
||||
terminal integration.
|
||||
- Explore the full range of [User guides](../cli/index.md#user-guides).
|
||||
|
||||
+125
-100
@@ -1,121 +1,146 @@
|
||||
# Gemini CLI documentation
|
||||
|
||||
Gemini CLI is an open-source AI agent that brings the power of Gemini directly
|
||||
into your terminal. It is designed to be a terminal-first, extensible, and
|
||||
powerful tool for developers, engineers, SREs, and beyond.
|
||||
|
||||
Gemini CLI integrates with your local environment. It can read and edit files,
|
||||
execute shell commands, and search the web, all while maintaining your project
|
||||
Gemini CLI brings the power of Gemini models directly into your terminal. Use it
|
||||
to understand code, automate tasks, and build workflows with your local project
|
||||
context.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
## Get started
|
||||
|
||||
Begin your journey with Gemini CLI by setting up your environment and learning
|
||||
the basics.
|
||||
Jump in to Gemini CLI.
|
||||
|
||||
- **[Quickstart](./get-started/index.md):** A streamlined guide to get you
|
||||
chatting in minutes.
|
||||
- **[Installation](./get-started/installation.md):** Instructions for macOS,
|
||||
Linux, and Windows.
|
||||
- **[Authentication](./get-started/authentication.md):** Set up access using
|
||||
Google OAuth, API keys, or Vertex AI.
|
||||
- **[Examples](./get-started/examples.md):** View common usage scenarios to
|
||||
inspire your own workflows.
|
||||
- **[Quickstart](./get-started/index.md):** Your first session with Gemini CLI.
|
||||
- **[Installation](./get-started/installation.md):** How to install Gemini CLI
|
||||
on your system.
|
||||
- **[Authentication](./get-started/authentication.md):** Setup instructions for
|
||||
personal and enterprise accounts.
|
||||
- **[Examples](./get-started/examples.md):** Practical examples of Gemini CLI in
|
||||
action.
|
||||
- **[Cheatsheet](./cli/cli-reference.md):** A quick reference for common
|
||||
commands and options.
|
||||
|
||||
## Use Gemini CLI
|
||||
|
||||
Master the core capabilities that let Gemini CLI interact with your system
|
||||
safely and effectively.
|
||||
User-focused guides and tutorials for daily development workflows.
|
||||
|
||||
- **[Using the CLI](./cli/index.md):** Learn the basics of the command-line
|
||||
interface.
|
||||
- **[File management](./tools/file-system.md):** Grant the model the ability to
|
||||
read code and apply changes directly to your files.
|
||||
- **[Shell commands](./tools/shell.md):** Allow the model to run builds, tests,
|
||||
and git commands.
|
||||
- **[Memory management](./tools/memory.md):** Teach Gemini CLI facts about your
|
||||
project and preferences that persist across sessions.
|
||||
- **[Project context](./cli/gemini-md.md):** Use `GEMINI.md` files to provide
|
||||
persistent context for your projects.
|
||||
- **[Web search and fetch](./tools/web-search.md):** Enable the model to fetch
|
||||
real-time information from the internet.
|
||||
- **[Session management](./cli/session-management.md):** Save, resume, and
|
||||
organize your chat sessions.
|
||||
- **[File management](./cli/tutorials/file-management.md):** How to work with
|
||||
local files and directories.
|
||||
- **[Manage context and memory](./cli/tutorials/memory-management.md):**
|
||||
Managing persistent instructions and facts.
|
||||
- **[Execute shell commands](./cli/tutorials/shell-commands.md):** Executing
|
||||
system commands safely.
|
||||
- **[Manage sessions and history](./cli/tutorials/session-management.md):**
|
||||
Resuming, managing, and rewinding conversations.
|
||||
- **[Plan tasks with todos](./cli/tutorials/task-planning.md):** Using todos for
|
||||
complex workflows.
|
||||
- **[Web search and fetch](./cli/tutorials/web-tools.md):** Searching and
|
||||
fetching content from the web.
|
||||
- **[Get started with skills](./cli/tutorials/skills-getting-started.md):**
|
||||
Getting started with specialized expertise.
|
||||
|
||||
## Features
|
||||
|
||||
Technical reference documentation for each capability of Gemini CLI.
|
||||
|
||||
- **[/about](./cli/commands.md#about):** About Gemini CLI.
|
||||
- **[/auth](./get-started/authentication.md):** Authentication.
|
||||
- **[/bug](./cli/commands.md#bug):** Report a bug.
|
||||
- **[/chat](./cli/commands.md#chat):** Chat history.
|
||||
- **[/clear](./cli/commands.md#clear):** Clear screen.
|
||||
- **[/compress](./cli/commands.md#compress):** Compress context.
|
||||
- **[/copy](./cli/commands.md#copy):** Copy output.
|
||||
- **[/directory](./cli/commands.md#directory-or-dir):** Manage workspace.
|
||||
- **[/docs](./cli/commands.md#docs):** Open documentation.
|
||||
- **[/editor](./cli/commands.md#editor):** Select editor.
|
||||
- **[/extensions](./extensions/index.md):** Manage extensions.
|
||||
- **[/help](./cli/commands.md#help-or):** Show help.
|
||||
- **[/hooks](./hooks/index.md):** Hooks.
|
||||
- **[/ide](./ide-integration/index.md):** IDE integration.
|
||||
- **[/init](./cli/commands.md#init):** Initialize context.
|
||||
- **[/mcp](./tools/mcp-server.md):** MCP servers.
|
||||
- **[/memory](./cli/commands.md#memory):** Manage memory.
|
||||
- **[/model](./cli/model.md):** Model selection.
|
||||
- **[/policies](./cli/commands.md#policies):** Manage policies.
|
||||
- **[/privacy](./cli/commands.md#privacy):** Privacy notice.
|
||||
- **[/quit](./cli/commands.md#quit-or-exit):** Exit CLI.
|
||||
- **[/restore](./cli/checkpointing.md):** Restore files.
|
||||
- **[/resume](./cli/commands.md#resume):** Resume session.
|
||||
- **[/rewind](./cli/rewind.md):** Rewind.
|
||||
- **[/settings](./cli/settings.md):** Settings.
|
||||
- **[/setup-github](./cli/commands.md#setup-github):** GitHub setup.
|
||||
- **[/shells](./cli/commands.md#shells-or-bashes):** Manage processes.
|
||||
- **[/skills](./cli/skills.md):** Agent skills.
|
||||
- **[/stats](./cli/commands.md#stats):** Session statistics.
|
||||
- **[/terminal-setup](./cli/commands.md#terminal-setup):** Terminal keybindings.
|
||||
- **[/theme](./cli/themes.md):** Themes.
|
||||
- **[/tools](./cli/commands.md#tools):** List tools.
|
||||
- **[/vim](./cli/commands.md#vim):** Vim mode.
|
||||
- **[Activate skill (tool)](./tools/activate-skill.md):** Internal mechanism for
|
||||
loading expert procedures.
|
||||
- **[Ask user (tool)](./tools/ask-user.md):** Internal dialog system for
|
||||
clarification.
|
||||
- **[Checkpointing](./cli/checkpointing.md):** Automatic session snapshots.
|
||||
- **[File system (tool)](./tools/file-system.md):** Technical details for local
|
||||
file operations.
|
||||
- **[Headless mode](./cli/headless.md):** Programmatic and scripting interface.
|
||||
- **[Internal documentation (tool)](./tools/internal-docs.md):** Technical
|
||||
lookup for CLI features.
|
||||
- **[Memory (tool)](./tools/memory.md):** Storage details for persistent facts.
|
||||
- **[Model routing](./cli/model-routing.md):** Automatic fallback resilience.
|
||||
- **[Plan mode (experimental)](./cli/plan-mode.md):** Use a safe, read-only mode
|
||||
for planning complex changes.
|
||||
- **[Sandboxing](./cli/sandbox.md):** Isolate tool execution.
|
||||
- **[Shell (tool)](./tools/shell.md):** Detailed system execution parameters.
|
||||
- **[Telemetry](./cli/telemetry.md):** Usage and performance metric details.
|
||||
- **[Todo (tool)](./tools/todos.md):** Progress tracking specification.
|
||||
- **[Token caching](./cli/token-caching.md):** Performance optimization.
|
||||
- **[Web fetch (tool)](./tools/web-fetch.md):** URL retrieval and extraction
|
||||
details.
|
||||
- **[Web search (tool)](./tools/web-search.md):** Google Search integration
|
||||
technicals.
|
||||
|
||||
## Configuration
|
||||
|
||||
Customize Gemini CLI to match your workflow and preferences.
|
||||
Settings and customization options for Gemini CLI.
|
||||
|
||||
- **[Settings](./cli/settings.md):** Control response creativity, output
|
||||
verbosity, and more.
|
||||
- **[Model selection](./cli/model.md):** Choose the best Gemini model for your
|
||||
specific task.
|
||||
- **[Ignore files](./cli/gemini-ignore.md):** Use `.geminiignore` to keep
|
||||
sensitive files out of the model's context.
|
||||
- **[Trusted folders](./cli/trusted-folders.md):** Define security boundaries
|
||||
for file access and execution.
|
||||
- **[Token caching](./cli/token-caching.md):** Optimize performance and cost by
|
||||
caching context.
|
||||
- **[Themes](./cli/themes.md):** Personalize the visual appearance of the CLI.
|
||||
- **[Custom commands](./cli/custom-commands.md):** Personalized shortcuts.
|
||||
- **[Enterprise configuration](./cli/enterprise.md):** Professional environment
|
||||
controls.
|
||||
- **[Ignore files (.geminiignore)](./cli/gemini-ignore.md):** Exclusion pattern
|
||||
reference.
|
||||
- **[Model configuration](./cli/generation-settings.md):** Fine-tune generation
|
||||
parameters like temperature and thinking budget.
|
||||
- **[Project context (GEMINI.md)](./cli/gemini-md.md):** Technical hierarchy of
|
||||
context files.
|
||||
- **[Settings](./cli/settings.md):** Full configuration reference.
|
||||
- **[System prompt override](./cli/system-prompt.md):** Instruction replacement
|
||||
logic.
|
||||
- **[Themes](./cli/themes.md):** UI personalization technical guide.
|
||||
- **[Trusted folders](./cli/trusted-folders.md):** Security permission logic.
|
||||
|
||||
## Advanced features
|
||||
## Reference
|
||||
|
||||
Explore powerful features for complex workflows and enterprise environments.
|
||||
Deep technical documentation and API specifications.
|
||||
|
||||
- **[Headless mode](./cli/headless.md):** Run Gemini CLI in scripts or CI/CD
|
||||
pipelines for automated reasoning.
|
||||
- **[Sandboxing](./cli/sandbox.md):** Execute untrusted code or tools in a
|
||||
secure, isolated container.
|
||||
- **[Checkpointing](./cli/checkpointing.md):** Save and restore workspace state
|
||||
to recover from experimental changes.
|
||||
- **[Custom commands](./cli/custom-commands.md):** Create shortcuts for
|
||||
frequently used prompts.
|
||||
- **[System prompt override](./cli/system-prompt.md):** Customize the core
|
||||
instructions given to the model.
|
||||
- **[Telemetry](./cli/telemetry.md):** Understand how usage data is collected
|
||||
and managed.
|
||||
- **[Enterprise](./cli/enterprise.md):** Manage configurations and policies for
|
||||
large teams.
|
||||
- **[Architecture overview](./architecture.md):** System design and components.
|
||||
- **[Command reference](./cli/commands.md):** Detailed slash command guide.
|
||||
- **[Configuration reference](./get-started/configuration.md):** Settings and
|
||||
environment variables.
|
||||
- **[Core concepts](./core/concepts.md):** Fundamental terminology and
|
||||
definitions.
|
||||
- **[Keyboard shortcuts](./cli/keyboard-shortcuts.md):** Productivity tips.
|
||||
- **[Policy engine](./core/policy-engine.md):** Fine-grained execution control.
|
||||
|
||||
## Extensions
|
||||
## Resources
|
||||
|
||||
Extend Gemini CLI's capabilities with new tools and behaviors using extensions.
|
||||
Support, release history, and legal information.
|
||||
|
||||
- **[Introduction](./extensions/index.md):** Learn about the extension system
|
||||
and how to manage extensions.
|
||||
- **[Writing extensions](./extensions/writing-extensions.md):** Learn how to
|
||||
create your first extension.
|
||||
- **[Extensions reference](./extensions/reference.md):** Deeply understand the
|
||||
extension format, commands, and configuration.
|
||||
- **[Best practices](./extensions/best-practices.md):** Learn strategies for
|
||||
building great extensions.
|
||||
- **[Extensions releasing](./extensions/releasing.md):** Learn how to share your
|
||||
extensions with the world.
|
||||
|
||||
## Ecosystem and extensibility
|
||||
|
||||
Connect Gemini CLI to external services and other development tools.
|
||||
|
||||
- **[MCP servers](./tools/mcp-server.md):** Connect to external services using
|
||||
the Model Context Protocol.
|
||||
- **[IDE integration](./ide-integration/index.md):** Use Gemini CLI alongside VS
|
||||
Code.
|
||||
- **[Hooks](./hooks/index.md):** Write scripts that run on specific CLI events.
|
||||
- **[Agent skills](./cli/skills.md):** Add specialized expertise and workflows.
|
||||
- **[Sub-agents](./core/subagents.md):** (Preview) Delegate tasks to specialized
|
||||
agents.
|
||||
|
||||
## Development and reference
|
||||
|
||||
Deep dive into the architecture and contribute to the project.
|
||||
|
||||
- **[Architecture](./architecture.md):** Understand the technical design of
|
||||
Gemini CLI.
|
||||
- **[Command reference](./cli/commands.md):** A complete list of available
|
||||
commands.
|
||||
- **[Local development](./local-development.md):** Set up your environment to
|
||||
contribute to Gemini CLI.
|
||||
- **[Contributing](../CONTRIBUTING.md):** Learn how to submit pull requests and
|
||||
report issues.
|
||||
- **[FAQ](./faq.md):** Answers to common questions.
|
||||
- **[Troubleshooting](./troubleshooting.md):** Solutions for common issues.
|
||||
- **[FAQ](./faq.md):** Answers to frequently asked questions.
|
||||
- **[Changelogs](./changelogs/index.md):** Highlights and notable changes.
|
||||
- **[Quota and pricing](./quota-and-pricing.md):** Limits and billing details.
|
||||
- **[Terms and privacy](./tos-privacy.md):** Official notices and terms.
|
||||
|
||||
+163
-77
@@ -7,108 +7,190 @@
|
||||
{ "label": "Installation", "slug": "docs/get-started/installation" },
|
||||
{ "label": "Authentication", "slug": "docs/get-started/authentication" },
|
||||
{ "label": "Examples", "slug": "docs/get-started/examples" },
|
||||
{ "label": "Gemini 3 (preview)", "slug": "docs/get-started/gemini-3" },
|
||||
{ "label": "CLI Reference", "slug": "docs/cli/cli-reference" }
|
||||
{ "label": "CLI cheatsheet", "slug": "docs/cli/cli-reference" },
|
||||
{ "label": "Gemini 3 on Gemini CLI", "slug": "docs/get-started/gemini-3" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Use Gemini CLI",
|
||||
"items": [
|
||||
{ "label": "Using the CLI", "slug": "docs/cli" },
|
||||
{ "label": "File management", "slug": "docs/tools/file-system" },
|
||||
{ "label": "Memory management", "slug": "docs/tools/memory" },
|
||||
{ "label": "Project context (GEMINI.md)", "slug": "docs/cli/gemini-md" },
|
||||
{ "label": "Shell commands", "slug": "docs/tools/shell" },
|
||||
{ "label": "Session management", "slug": "docs/cli/session-management" },
|
||||
{
|
||||
"label": "File management",
|
||||
"slug": "docs/cli/tutorials/file-management"
|
||||
},
|
||||
{
|
||||
"label": "Manage context and memory",
|
||||
"slug": "docs/cli/tutorials/memory-management"
|
||||
},
|
||||
{
|
||||
"label": "Execute shell commands",
|
||||
"slug": "docs/cli/tutorials/shell-commands"
|
||||
},
|
||||
{
|
||||
"label": "Manage sessions and history",
|
||||
"slug": "docs/cli/tutorials/session-management"
|
||||
},
|
||||
{
|
||||
"label": "Plan tasks with todos",
|
||||
"slug": "docs/cli/tutorials/task-planning"
|
||||
},
|
||||
{
|
||||
"label": "Web search and fetch",
|
||||
"slug": "docs/cli/tutorials/web-tools"
|
||||
},
|
||||
{
|
||||
"label": "Get started with skills",
|
||||
"slug": "docs/cli/tutorials/skills-getting-started"
|
||||
},
|
||||
{
|
||||
"label": "Set up an MCP server",
|
||||
"slug": "docs/cli/tutorials/mcp-setup"
|
||||
},
|
||||
{ "label": "Automate tasks", "slug": "docs/cli/tutorials/automation" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Features",
|
||||
"items": [
|
||||
{
|
||||
"label": "/about - About Gemini CLI",
|
||||
"slug": "docs/cli/commands#about"
|
||||
},
|
||||
{
|
||||
"label": "/auth - Authentication",
|
||||
"slug": "docs/get-started/authentication"
|
||||
},
|
||||
{ "label": "/bug - Report a bug", "slug": "docs/cli/commands#bug" },
|
||||
{ "label": "/chat - Chat history", "slug": "docs/cli/commands#chat" },
|
||||
{ "label": "/clear - Clear screen", "slug": "docs/cli/commands#clear" },
|
||||
{
|
||||
"label": "/compress - Compress context",
|
||||
"slug": "docs/cli/commands#compress"
|
||||
},
|
||||
{ "label": "/copy - Copy output", "slug": "docs/cli/commands#copy" },
|
||||
{
|
||||
"label": "/directory - Manage workspace",
|
||||
"slug": "docs/cli/commands#directory-or-dir"
|
||||
},
|
||||
{
|
||||
"label": "/docs - Open documentation",
|
||||
"slug": "docs/cli/commands#docs"
|
||||
},
|
||||
{
|
||||
"label": "/editor - Select editor",
|
||||
"slug": "docs/cli/commands#editor"
|
||||
},
|
||||
{
|
||||
"label": "/extensions - Manage extensions",
|
||||
"slug": "docs/extensions/index"
|
||||
},
|
||||
{ "label": "/help - Show help", "slug": "docs/cli/commands#help-or" },
|
||||
{ "label": "/hooks - Hooks", "slug": "docs/hooks" },
|
||||
{ "label": "/ide - IDE integration", "slug": "docs/ide-integration" },
|
||||
{
|
||||
"label": "/init - Initialize context",
|
||||
"slug": "docs/cli/commands#init"
|
||||
},
|
||||
{ "label": "/mcp - MCP servers", "slug": "docs/tools/mcp-server" },
|
||||
|
||||
{
|
||||
"label": "/memory - Manage memory",
|
||||
"slug": "docs/cli/commands#memory"
|
||||
},
|
||||
{ "label": "/model - Model selection", "slug": "docs/cli/model" },
|
||||
{
|
||||
"label": "/policies - Manage policies",
|
||||
"slug": "docs/cli/commands#policies"
|
||||
},
|
||||
{
|
||||
"label": "/privacy - Privacy notice",
|
||||
"slug": "docs/cli/commands#privacy"
|
||||
},
|
||||
{ "label": "/quit - Exit CLI", "slug": "docs/cli/commands#quit-or-exit" },
|
||||
{ "label": "/restore - Restore files", "slug": "docs/cli/checkpointing" },
|
||||
{
|
||||
"label": "/resume - Resume session",
|
||||
|
||||
"slug": "docs/cli/commands#resume"
|
||||
},
|
||||
{ "label": "/rewind - Rewind", "slug": "docs/cli/rewind" },
|
||||
{ "label": "/settings - Settings", "slug": "docs/cli/settings" },
|
||||
{
|
||||
"label": "/setup-github - GitHub setup",
|
||||
"slug": "docs/cli/commands#setup-github"
|
||||
},
|
||||
{
|
||||
"label": "/shells - Manage processes",
|
||||
"slug": "docs/cli/commands#shells-or-bashes"
|
||||
},
|
||||
{ "label": "/skills - Agent skills", "slug": "docs/cli/skills" },
|
||||
{
|
||||
"label": "/stats - Session statistics",
|
||||
"slug": "docs/cli/commands#stats"
|
||||
},
|
||||
{
|
||||
"label": "/terminal-setup - Terminal keybindings",
|
||||
"slug": "docs/cli/commands#terminal-setup"
|
||||
},
|
||||
{ "label": "/theme - Themes", "slug": "docs/cli/themes" },
|
||||
{ "label": "/tools - List tools", "slug": "docs/cli/commands#tools" },
|
||||
{ "label": "/vim - Vim mode", "slug": "docs/cli/commands#vim" },
|
||||
|
||||
{
|
||||
"label": "Activate skill (tool)",
|
||||
"slug": "docs/tools/activate-skill"
|
||||
},
|
||||
{ "label": "Ask user (tool)", "slug": "docs/tools/ask-user" },
|
||||
{ "label": "Checkpointing", "slug": "docs/cli/checkpointing" },
|
||||
{ "label": "File system (tool)", "slug": "docs/tools/file-system" },
|
||||
{ "label": "Headless mode", "slug": "docs/cli/headless" },
|
||||
{
|
||||
"label": "Internal documentation (tool)",
|
||||
"slug": "docs/tools/internal-docs"
|
||||
},
|
||||
{ "label": "Memory (tool)", "slug": "docs/tools/memory" },
|
||||
{ "label": "Model routing", "slug": "docs/cli/model-routing" },
|
||||
{ "label": "Plan mode (experimental)", "slug": "docs/cli/plan-mode" },
|
||||
{ "label": "Todos", "slug": "docs/tools/todos" },
|
||||
{ "label": "Web search and fetch", "slug": "docs/tools/web-search" }
|
||||
{ "label": "Sandboxing", "slug": "docs/cli/sandbox" },
|
||||
{ "label": "Shell (tool)", "slug": "docs/tools/shell" },
|
||||
{ "label": "Telemetry", "slug": "docs/cli/telemetry" },
|
||||
{ "label": "Todo (tool)", "slug": "docs/tools/todos" },
|
||||
{ "label": "Token caching", "slug": "docs/cli/token-caching" },
|
||||
{ "label": "Web fetch (tool)", "slug": "docs/tools/web-fetch" },
|
||||
{ "label": "Web search (tool)", "slug": "docs/tools/web-search" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Configuration",
|
||||
"items": [
|
||||
{ "label": "Custom commands", "slug": "docs/cli/custom-commands" },
|
||||
{ "label": "Enterprise configuration", "slug": "docs/cli/enterprise" },
|
||||
{
|
||||
"label": "Ignore files (.geminiignore)",
|
||||
"slug": "docs/cli/gemini-ignore"
|
||||
},
|
||||
{ "label": "Model selection", "slug": "docs/cli/model" },
|
||||
{
|
||||
"label": "Model configuration",
|
||||
"slug": "docs/cli/generation-settings"
|
||||
},
|
||||
{ "label": "Project context (GEMINI.md)", "slug": "docs/cli/gemini-md" },
|
||||
{ "label": "Settings", "slug": "docs/cli/settings" },
|
||||
{ "label": "Themes", "slug": "docs/cli/themes" },
|
||||
{ "label": "Token caching", "slug": "docs/cli/token-caching" },
|
||||
{ "label": "Trusted folders", "slug": "docs/cli/trusted-folders" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Advanced features",
|
||||
"items": [
|
||||
{ "label": "Checkpointing", "slug": "docs/cli/checkpointing" },
|
||||
{ "label": "Custom commands", "slug": "docs/cli/custom-commands" },
|
||||
{ "label": "Enterprise features", "slug": "docs/cli/enterprise" },
|
||||
{
|
||||
"label": "Enterprise admin controls",
|
||||
"slug": "docs/admin/enterprise-controls"
|
||||
},
|
||||
{ "label": "Headless mode & scripting", "slug": "docs/cli/headless" },
|
||||
{ "label": "Sandboxing", "slug": "docs/cli/sandbox" },
|
||||
{ "label": "System prompt override", "slug": "docs/cli/system-prompt" },
|
||||
{ "label": "Telemetry", "slug": "docs/cli/telemetry" }
|
||||
{ "label": "Themes", "slug": "docs/cli/themes" },
|
||||
{ "label": "Trusted folders", "slug": "docs/cli/trusted-folders" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Extensions",
|
||||
"items": [
|
||||
{
|
||||
"label": "Introduction",
|
||||
"slug": "docs/extensions"
|
||||
},
|
||||
{ "label": "Introduction", "slug": "docs/extensions" },
|
||||
{
|
||||
"label": "Writing extensions",
|
||||
"slug": "docs/extensions/writing-extensions"
|
||||
},
|
||||
{
|
||||
"label": "Extensions reference",
|
||||
"slug": "docs/extensions/reference"
|
||||
},
|
||||
{
|
||||
"label": "Best practices",
|
||||
"slug": "docs/extensions/best-practices"
|
||||
},
|
||||
{
|
||||
"label": "Extensions releasing",
|
||||
"slug": "docs/extensions/releasing"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Ecosystem and extensibility",
|
||||
"items": [
|
||||
{ "label": "Agent skills", "slug": "docs/cli/skills" },
|
||||
{
|
||||
"label": "Creating Agent skills",
|
||||
"slug": "docs/cli/creating-skills"
|
||||
},
|
||||
{
|
||||
"label": "Sub-agents (experimental)",
|
||||
"slug": "docs/core/subagents"
|
||||
},
|
||||
{
|
||||
"label": "Remote subagents (experimental)",
|
||||
"slug": "docs/core/remote-agents"
|
||||
},
|
||||
{ "label": "Hooks", "slug": "docs/hooks" },
|
||||
{ "label": "IDE integration", "slug": "docs/ide-integration" },
|
||||
{ "label": "MCP servers", "slug": "docs/tools/mcp-server" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Tutorials",
|
||||
"items": [
|
||||
{
|
||||
"label": "Get started with extensions",
|
||||
"slug": "docs/extensions/writing-extensions"
|
||||
},
|
||||
{ "label": "How to write hooks", "slug": "docs/hooks/writing-hooks" }
|
||||
{ "label": "Reference", "slug": "docs/extensions/reference" },
|
||||
{ "label": "Best practices", "slug": "docs/extensions/best-practices" },
|
||||
{ "label": "Releasing", "slug": "docs/extensions/releasing" }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -116,7 +198,11 @@
|
||||
"items": [
|
||||
{ "label": "Architecture", "slug": "docs/architecture" },
|
||||
{ "label": "Command reference", "slug": "docs/cli/commands" },
|
||||
{ "label": "Configuration", "slug": "docs/get-started/configuration" },
|
||||
{
|
||||
"label": "Configuration reference",
|
||||
"slug": "docs/get-started/configuration"
|
||||
},
|
||||
{ "label": "Core concepts", "slug": "docs/core/concepts" },
|
||||
{ "label": "Keyboard shortcuts", "slug": "docs/cli/keyboard-shortcuts" },
|
||||
{ "label": "Memory import processor", "slug": "docs/core/memport" },
|
||||
{ "label": "Policy engine", "slug": "docs/core/policy-engine" },
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Activate skill tool (`activate_skill`)
|
||||
|
||||
The `activate_skill` tool lets Gemini CLI load specialized procedural expertise
|
||||
and resources when they are relevant to your request.
|
||||
|
||||
## Description
|
||||
|
||||
Skills are packages of instructions and tools designed for specific engineering
|
||||
tasks, such as reviewing code or creating pull requests. Gemini CLI uses this
|
||||
tool to "activate" a skill, which provides it with detailed guidelines and
|
||||
specialized tools tailored to that task.
|
||||
|
||||
### Arguments
|
||||
|
||||
`activate_skill` takes one argument:
|
||||
|
||||
- `name` (enum, required): The name of the skill to activate (for example,
|
||||
`code-reviewer`, `pr-creator`, or `docs-writer`).
|
||||
|
||||
## Usage
|
||||
|
||||
The `activate_skill` tool is used exclusively by the Gemini agent. You cannot
|
||||
invoke this tool manually.
|
||||
|
||||
When the agent identifies that a task matches a discovered skill, it requests to
|
||||
activate that skill. Once activated, the agent's behavior is guided by the
|
||||
skill's specific instructions until the task is complete.
|
||||
|
||||
## Behavior
|
||||
|
||||
The agent uses this tool to provide professional-grade assistance:
|
||||
|
||||
- **Specialized logic:** Skills contain expert-level procedures for complex
|
||||
workflows.
|
||||
- **Dynamic capability:** Activating a skill can grant the agent access to new,
|
||||
task-specific tools.
|
||||
- **Contextual awareness:** Skills help the agent focus on the most relevant
|
||||
standards and conventions for a particular task.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn how to [Use Agent Skills](../cli/skills.md).
|
||||
- See the [Creating Agent Skills](../cli/creating-skills.md) guide.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Ask User Tool
|
||||
|
||||
The `ask_user` tool allows the agent to ask you one or more questions to gather
|
||||
The `ask_user` tool lets Gemini CLI ask you one or more questions to gather
|
||||
preferences, clarify requirements, or make decisions. It supports multiple
|
||||
question types including multiple-choice, free-form text, and Yes/No
|
||||
confirmation.
|
||||
|
||||
+41
-131
@@ -1,99 +1,49 @@
|
||||
# Gemini CLI file system tools
|
||||
# File system tools reference
|
||||
|
||||
The Gemini CLI provides a comprehensive suite of tools for interacting with the
|
||||
local file system. These tools allow the Gemini model to read from, write to,
|
||||
list, search, and modify files and directories, all under your control and
|
||||
typically with confirmation for sensitive operations.
|
||||
The Gemini CLI core provides a suite of tools for interacting with the local
|
||||
file system. These tools allow the model to explore and modify your codebase.
|
||||
|
||||
**Note:** All file system tools operate within a `rootDirectory` (usually the
|
||||
current working directory where you launched the CLI) for security. Paths that
|
||||
you provide to these tools are generally expected to be absolute or are resolved
|
||||
relative to this root directory.
|
||||
## Technical reference
|
||||
|
||||
## 1. `list_directory` (ReadFolder)
|
||||
All file system tools operate within a `rootDirectory` (the current working
|
||||
directory or workspace root) for security.
|
||||
|
||||
`list_directory` lists the names of files and subdirectories directly within a
|
||||
specified directory path. It can optionally ignore entries matching provided
|
||||
glob patterns.
|
||||
### `list_directory` (ReadFolder)
|
||||
|
||||
Lists the names of files and subdirectories directly within a specified path.
|
||||
|
||||
- **Tool name:** `list_directory`
|
||||
- **Display name:** ReadFolder
|
||||
- **File:** `ls.ts`
|
||||
- **Parameters:**
|
||||
- `path` (string, required): The absolute path to the directory to list.
|
||||
- `ignore` (array of strings, optional): A list of glob patterns to exclude
|
||||
from the listing (e.g., `["*.log", ".git"]`).
|
||||
- `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`
|
||||
patterns when listing files. Defaults to `true`.
|
||||
- **Behavior:**
|
||||
- Returns a list of file and directory names.
|
||||
- Indicates whether each entry is a directory.
|
||||
- Sorts entries with directories first, then alphabetically.
|
||||
- **Output (`llmContent`):** A string like:
|
||||
`Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
|
||||
- **Confirmation:** No.
|
||||
- **Arguments:**
|
||||
- `dir_path` (string, required): Absolute or relative path to the directory.
|
||||
- `ignore` (array, optional): Glob patterns to exclude.
|
||||
- `file_filtering_options` (object, optional): Configuration for `.gitignore`
|
||||
and `.geminiignore` compliance.
|
||||
|
||||
## 2. `read_file` (ReadFile)
|
||||
### `read_file` (ReadFile)
|
||||
|
||||
`read_file` reads and returns the content of a specified file. This tool handles
|
||||
text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
|
||||
OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
|
||||
Other binary file types are generally skipped.
|
||||
Reads and returns the content of a specific file. Supports text, images, audio,
|
||||
and PDF.
|
||||
|
||||
- **Tool name:** `read_file`
|
||||
- **Display name:** ReadFile
|
||||
- **File:** `read-file.ts`
|
||||
- **Parameters:**
|
||||
- `path` (string, required): The absolute path to the file to read.
|
||||
- `offset` (number, optional): For text files, the 0-based line number to
|
||||
start reading from. Requires `limit` to be set.
|
||||
- `limit` (number, optional): For text files, the maximum number of lines to
|
||||
read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire
|
||||
file if feasible.
|
||||
- **Behavior:**
|
||||
- For text files: Returns the content. If `offset` and `limit` are used,
|
||||
returns only that slice of lines. Indicates if content was truncated due to
|
||||
line limits or line length limits.
|
||||
- For image, audio, and PDF files: Returns the file content as a
|
||||
base64-encoded data structure suitable for model consumption.
|
||||
- For other binary files: Attempts to identify and skip them, returning a
|
||||
message indicating it's a generic binary file.
|
||||
- **Output:** (`llmContent`):
|
||||
- For text files: The file content, potentially prefixed with a truncation
|
||||
message (e.g.,
|
||||
`[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
|
||||
- For image/audio/PDF files: An object containing `inlineData` with `mimeType`
|
||||
and base64 `data` (e.g.,
|
||||
`{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
|
||||
- For other binary files: A message like
|
||||
`Cannot display content of binary file: /path/to/data.bin`.
|
||||
- **Confirmation:** No.
|
||||
- **Arguments:**
|
||||
- `file_path` (string, required): Path to the file.
|
||||
- `offset` (number, optional): Start line for text files (0-based).
|
||||
- `limit` (number, optional): Maximum lines to read.
|
||||
|
||||
## 3. `write_file` (WriteFile)
|
||||
### `write_file` (WriteFile)
|
||||
|
||||
`write_file` writes content to a specified file. If the file exists, it will be
|
||||
overwritten. If the file doesn't exist, it (and any necessary parent
|
||||
directories) will be created.
|
||||
Writes content to a specified file, overwriting it if it exists or creating it
|
||||
if not.
|
||||
|
||||
- **Tool name:** `write_file`
|
||||
- **Display name:** WriteFile
|
||||
- **File:** `write-file.ts`
|
||||
- **Parameters:**
|
||||
- `file_path` (string, required): The absolute path to the file to write to.
|
||||
- `content` (string, required): The content to write into the file.
|
||||
- **Behavior:**
|
||||
- Writes the provided `content` to the `file_path`.
|
||||
- Creates parent directories if they don't exist.
|
||||
- **Output (`llmContent`):** A success message, e.g.,
|
||||
`Successfully overwrote file: /path/to/your/file.txt` or
|
||||
`Successfully created and wrote to new file: /path/to/new/file.txt`.
|
||||
- **Confirmation:** Yes. Shows a diff of changes and asks for user approval
|
||||
before writing.
|
||||
- **Arguments:**
|
||||
- `file_path` (string, required): Path to the file.
|
||||
- `content` (string, required): Data to write.
|
||||
- **Confirmation:** Requires manual user approval.
|
||||
|
||||
## 4. `glob` (FindFiles)
|
||||
### `glob` (FindFiles)
|
||||
|
||||
`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
|
||||
`*.md`), returning absolute paths sorted by modification time (newest first).
|
||||
Finds files matching specific glob patterns across the workspace.
|
||||
|
||||
- **Tool name:** `glob`
|
||||
- **Display name:** FindFiles
|
||||
@@ -161,56 +111,16 @@ This tool is designed for precise, targeted changes and requires significant
|
||||
context around the `old_string` to ensure it modifies the correct location.
|
||||
|
||||
- **Tool name:** `replace`
|
||||
- **Display name:** Edit
|
||||
- **File:** `edit.ts`
|
||||
- **Parameters:**
|
||||
- `file_path` (string, required): The absolute path to the file to modify.
|
||||
- `old_string` (string, required): The exact literal text to replace.
|
||||
- **Arguments:**
|
||||
- `file_path` (string, required): Path to the file.
|
||||
- `instruction` (string, required): Semantic description of the change.
|
||||
- `old_string` (string, required): Exact literal text to find.
|
||||
- `new_string` (string, required): Exact literal text to replace with.
|
||||
- **Confirmation:** Requires manual user approval.
|
||||
|
||||
**CRITICAL:** This string must uniquely identify the single instance to
|
||||
change. It should include at least 3 lines of context _before_ and _after_
|
||||
the target text, matching whitespace and indentation precisely. If
|
||||
`old_string` is empty, the tool attempts to create a new file at `file_path`
|
||||
with `new_string` as content.
|
||||
## Next steps
|
||||
|
||||
- `new_string` (string, required): The exact literal text to replace
|
||||
`old_string` with.
|
||||
- `expected_replacements` (number, optional): The number of occurrences to
|
||||
replace. Defaults to `1`.
|
||||
|
||||
- **Behavior:**
|
||||
- If `old_string` is empty and `file_path` does not exist, creates a new file
|
||||
with `new_string` as content.
|
||||
- If `old_string` is provided, it reads the `file_path` and attempts to find
|
||||
exactly one occurrence of `old_string`.
|
||||
- If one occurrence is found, it replaces it with `new_string`.
|
||||
- **Enhanced reliability (multi-stage edit correction):** To significantly
|
||||
improve the success rate of edits, especially when the model-provided
|
||||
`old_string` might not be perfectly precise, the tool incorporates a
|
||||
multi-stage edit correction mechanism.
|
||||
- If the initial `old_string` isn't found or matches multiple locations, the
|
||||
tool can leverage the Gemini model to iteratively refine `old_string` (and
|
||||
potentially `new_string`).
|
||||
- This self-correction process attempts to identify the unique segment the
|
||||
model intended to modify, making the `replace` operation more robust even
|
||||
with slightly imperfect initial context.
|
||||
- **Failure conditions:** Despite the correction mechanism, the tool will fail
|
||||
if:
|
||||
- `file_path` is not absolute or is outside the root directory.
|
||||
- `old_string` is not empty, but the `file_path` does not exist.
|
||||
- `old_string` is empty, but the `file_path` already exists.
|
||||
- `old_string` is not found in the file after attempts to correct it.
|
||||
- `old_string` is found multiple times, and the self-correction mechanism
|
||||
cannot resolve it to a single, unambiguous match.
|
||||
- **Output (`llmContent`):**
|
||||
- On success:
|
||||
`Successfully modified file: /path/to/file.txt (1 replacements).` or
|
||||
`Created new file: /path/to/new_file.txt with provided content.`
|
||||
- On failure: An error message explaining the reason (e.g.,
|
||||
`Failed to edit, 0 occurrences found...`,
|
||||
`Failed to edit, expected 1 occurrences but found 2...`).
|
||||
- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user
|
||||
approval before writing to the file.
|
||||
|
||||
These file system tools provide a foundation for the Gemini CLI to understand
|
||||
and interact with your local project context.
|
||||
- Follow the [File management tutorial](../cli/tutorials/file-management.md) for
|
||||
practical examples.
|
||||
- Learn about [Trusted folders](../cli/trusted-folders.md) to manage access
|
||||
permissions.
|
||||
|
||||
+82
-81
@@ -1,101 +1,102 @@
|
||||
# Gemini CLI tools
|
||||
|
||||
The Gemini CLI includes built-in tools that the Gemini model uses to interact
|
||||
with your local environment, access information, and perform actions. These
|
||||
tools enhance the CLI's capabilities, enabling it to go beyond text generation
|
||||
and assist with a wide range of tasks.
|
||||
Gemini CLI uses tools to interact with your local environment, access
|
||||
information, and perform actions on your behalf. These tools extend the model's
|
||||
capabilities beyond text generation, letting it read files, execute commands,
|
||||
and search the web.
|
||||
|
||||
## Overview of Gemini CLI tools
|
||||
## User-triggered tools
|
||||
|
||||
In the context of the Gemini CLI, tools are specific functions or modules that
|
||||
the Gemini model can request to be executed. For example, if you ask Gemini to
|
||||
"Summarize the contents of `my_document.txt`," the model will likely identify
|
||||
the need to read that file and will request the execution of the `read_file`
|
||||
You can directly trigger these tools using special syntax in your prompts.
|
||||
|
||||
- **[File access](./file-system.md#read_many_files) (`@`):** Use the `@` symbol
|
||||
followed by a file or directory path to include its content in your prompt.
|
||||
This triggers the `read_many_files` tool.
|
||||
- **[Shell commands](./shell.md) (`!`):** Use the `!` symbol followed by a
|
||||
system command to execute it directly. This triggers the `run_shell_command`
|
||||
tool.
|
||||
|
||||
The core component (`packages/core`) manages these tools, presents their
|
||||
definitions (schemas) to the Gemini model, executes them when requested, and
|
||||
returns the results to the model for further processing into a user-facing
|
||||
response.
|
||||
## Model-triggered tools
|
||||
|
||||
These tools provide the following capabilities:
|
||||
The Gemini model automatically requests these tools when it needs to perform
|
||||
specific actions or gather information to fulfill your requests. You do not call
|
||||
these tools manually.
|
||||
|
||||
- **Access local information:** Tools allow Gemini to access your local file
|
||||
system, read file contents, list directories, etc.
|
||||
- **Execute commands:** With tools like `run_shell_command`, Gemini can run
|
||||
shell commands (with appropriate safety measures and user confirmation).
|
||||
- **Interact with the web:** Tools can fetch content from URLs.
|
||||
- **Take actions:** Tools can modify files, write new files, or perform other
|
||||
actions on your system (again, typically with safeguards).
|
||||
- **Ground responses:** By using tools to fetch real-time or specific local
|
||||
data, Gemini's responses can be more accurate, relevant, and grounded in your
|
||||
actual context.
|
||||
### File management
|
||||
|
||||
## How to use Gemini CLI tools
|
||||
These tools let the model explore and modify your local codebase.
|
||||
|
||||
To use Gemini CLI tools, provide a prompt to the Gemini CLI. The process works
|
||||
as follows:
|
||||
- **[Directory listing](./file-system.md#list_directory) (`list_directory`):**
|
||||
Lists files and subdirectories.
|
||||
- **[File reading](./file-system.md#read_file) (`read_file`):** Reads the
|
||||
content of a specific file.
|
||||
- **[File writing](./file-system.md#write_file) (`write_file`):** Creates or
|
||||
overwrites a file with new content.
|
||||
- **[File search](./file-system.md#glob) (`glob`):** Finds files matching a glob
|
||||
pattern.
|
||||
- **[Text search](./file-system.md#search_file_content)
|
||||
(`search_file_content`):** Searches for text within files using grep or
|
||||
ripgrep.
|
||||
- **[Text replacement](./file-system.md#replace) (`replace`):** Performs precise
|
||||
edits within a file.
|
||||
|
||||
1. You provide a prompt to the Gemini CLI.
|
||||
2. The CLI sends the prompt to the core.
|
||||
3. The core, along with your prompt and conversation history, sends a list of
|
||||
available tools and their descriptions/schemas to the Gemini API.
|
||||
4. The Gemini model analyzes your request. If it determines that a tool is
|
||||
needed, its response will include a request to execute a specific tool with
|
||||
certain parameters.
|
||||
5. The core receives this tool request, validates it, and (often after user
|
||||
confirmation for sensitive operations) executes the tool.
|
||||
6. The output from the tool is sent back to the Gemini model.
|
||||
7. The Gemini model uses the tool's output to formulate its final answer, which
|
||||
is then sent back through the core to the CLI and displayed to you.
|
||||
### Agent coordination
|
||||
|
||||
You will typically see messages in the CLI indicating when a tool is being
|
||||
called and whether it succeeded or failed.
|
||||
These tools help the model manage its plan and interact with you.
|
||||
|
||||
- **Ask user (`ask_user`):** Requests clarification or missing information from
|
||||
you via an interactive dialog.
|
||||
- **[Memory](./memory.md) (`save_memory`):** Saves important facts to your
|
||||
long-term memory (`GEMINI.md`).
|
||||
- **[Todos](./todos.md) (`write_todos`):** Manages a list of subtasks for
|
||||
complex plans.
|
||||
- **[Agent Skills](../cli/skills.md) (`activate_skill`):** Loads specialized
|
||||
procedural expertise when needed.
|
||||
- **Internal docs (`get_internal_docs`):** Accesses Gemini CLI's own
|
||||
documentation to help answer your questions.
|
||||
|
||||
### Information gathering
|
||||
|
||||
These tools provide the model with access to external data.
|
||||
|
||||
- **[Web fetch](./web-fetch.md) (`web_fetch`):** Retrieves and processes content
|
||||
from specific URLs.
|
||||
- **[Web search](./web-search.md) (`google_web_search`):** Performs a Google
|
||||
Search to find up-to-date information.
|
||||
|
||||
## How to use tools
|
||||
|
||||
You use tools indirectly by providing natural language prompts to Gemini CLI.
|
||||
|
||||
1. **Prompt:** You enter a request or use syntax like `@` or `!`.
|
||||
2. **Request:** The model analyzes your request and identifies if a tool is
|
||||
required.
|
||||
3. **Validation:** If a tool is needed, the CLI validates the parameters and
|
||||
checks your security settings.
|
||||
4. **Confirmation:** For sensitive operations (like writing files), the CLI
|
||||
prompts you for approval.
|
||||
5. **Execution:** The tool runs, and its output is sent back to the model.
|
||||
6. **Response:** The model uses the results to generate a final, grounded
|
||||
answer.
|
||||
|
||||
## Security and confirmation
|
||||
|
||||
Many tools, especially those that can modify your file system or execute
|
||||
commands (`write_file`, `edit`, `run_shell_command`), are designed with safety
|
||||
in mind. The Gemini CLI will typically:
|
||||
Safety is a core part of the tool system. To protect your system, Gemini CLI
|
||||
implements several safeguards.
|
||||
|
||||
- **Require confirmation:** Prompt you before executing potentially sensitive
|
||||
operations, showing you what action is about to be taken.
|
||||
- **Utilize sandboxing:** All tools are subject to restrictions enforced by
|
||||
sandboxing (see [Sandboxing in the Gemini CLI](../cli/sandbox.md)). This means
|
||||
that when operating in a sandbox, any tools (including MCP servers) you wish
|
||||
to use must be available _inside_ the sandbox environment. For example, to run
|
||||
an MCP server through `npx`, the `npx` executable must be installed within the
|
||||
sandbox's Docker image or be available in the `sandbox-exec` environment.
|
||||
- **User confirmation:** You must manually approve tools that modify files or
|
||||
execute shell commands. The CLI shows you a diff or the exact command before
|
||||
you confirm.
|
||||
- **Sandboxing:** You can run tool executions in secure, containerized
|
||||
environments to isolate changes from your host system. For more details, see
|
||||
the [Sandboxing](../cli/sandbox.md) guide.
|
||||
- **Trusted folders:** You can configure which directories allow the model to
|
||||
use system tools.
|
||||
|
||||
It's important to always review confirmation prompts carefully before allowing a
|
||||
tool to proceed.
|
||||
Always review confirmation prompts carefully before allowing a tool to execute.
|
||||
|
||||
## Learn more about Gemini CLI's tools
|
||||
## Next steps
|
||||
|
||||
Gemini CLI's built-in tools can be broadly categorized as follows:
|
||||
|
||||
- **[File System Tools](./file-system.md):** For interacting with files and
|
||||
directories (reading, writing, listing, searching, etc.).
|
||||
- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell
|
||||
- Learn how to [Provide context](../cli/gemini-md.md) to guide tool use.
|
||||
- Explore the [Command reference](../cli/commands.md) for tool-related slash
|
||||
commands.
|
||||
- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content
|
||||
from URLs.
|
||||
- **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching
|
||||
the web.
|
||||
- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
|
||||
information across sessions.
|
||||
- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
|
||||
requests.
|
||||
- **[Planning Tools](./planning.md):** For entering and exiting Plan Mode.
|
||||
- **[Ask User Tool](./ask-user.md) (`ask_user`):** For gathering user input and
|
||||
making decisions.
|
||||
|
||||
Additionally, these tools incorporate:
|
||||
|
||||
- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the
|
||||
Gemini model and your local environment or other services like APIs.
|
||||
- **[Agent Skills](../cli/skills.md)**: On-demand expertise packages that are
|
||||
activated via the `activate_skill` tool to provide specialized guidance and
|
||||
resources.
|
||||
- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
|
||||
changes from your environment to reduce potential risk.
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
# Internal documentation tool (`get_internal_docs`)
|
||||
|
||||
The `get_internal_docs` tool lets Gemini CLI access its own technical
|
||||
documentation to provide more accurate answers about its capabilities and usage.
|
||||
|
||||
## Description
|
||||
|
||||
This tool is used when Gemini CLI needs to verify specific details about Gemini
|
||||
CLI's internal features, built-in commands, or configuration options. It
|
||||
provides direct access to the Markdown files in the `docs/` directory.
|
||||
|
||||
### Arguments
|
||||
|
||||
`get_internal_docs` takes one optional argument:
|
||||
|
||||
- `path` (string, optional): The relative path to a specific documentation file
|
||||
(for example, `cli/commands.md`). If omitted, the tool returns a list of all
|
||||
available documentation paths.
|
||||
|
||||
## Usage
|
||||
|
||||
The `get_internal_docs` tool is used exclusively by Gemini CLI. You cannot
|
||||
invoke this tool manually.
|
||||
|
||||
When Gemini CLI uses this tool, it retrieves the content of the requested
|
||||
documentation file and processes it to answer your question. This ensures that
|
||||
the information provided by the AI is grounded in the latest project
|
||||
documentation.
|
||||
|
||||
## Behavior
|
||||
|
||||
Gemini CLI uses this tool to ensure technical accuracy:
|
||||
|
||||
- **Capability discovery:** If Gemini CLI is unsure how a feature works, it can
|
||||
lookup the corresponding documentation.
|
||||
- **Reference lookup:** Gemini CLI can verify slash command sub-commands or
|
||||
specific setting names.
|
||||
- **Self-correction:** Gemini CLI can use the documentation to correct its
|
||||
understanding of Gemini CLI's system logic.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore the [Command reference](../cli/commands.md) for a detailed guide to
|
||||
slash commands.
|
||||
- See the [Configuration guide](../get-started/configuration.md) for settings
|
||||
reference.
|
||||
@@ -101,8 +101,8 @@ execution.
|
||||
|
||||
#### Global MCP settings (`mcp`)
|
||||
|
||||
The `mcp` object in your `settings.json` allows you to define global rules for
|
||||
all MCP servers.
|
||||
The `mcp` object in your `settings.json` lets you define global rules for all
|
||||
MCP servers.
|
||||
|
||||
- **`mcp.serverCommand`** (string): A global command to start an MCP server.
|
||||
- **`mcp.allowed`** (array of strings): A list of MCP server names to allow. If
|
||||
|
||||
+21
-40
@@ -1,54 +1,35 @@
|
||||
# Memory tool (`save_memory`)
|
||||
|
||||
This document describes the `save_memory` tool for the Gemini CLI.
|
||||
The `save_memory` tool allows the Gemini agent to persist specific facts, user
|
||||
preferences, and project details across sessions.
|
||||
|
||||
## Description
|
||||
## Technical reference
|
||||
|
||||
Use `save_memory` to save and recall information across your Gemini CLI
|
||||
sessions. With `save_memory`, you can direct the CLI to remember key details
|
||||
across sessions, providing personalized and directed assistance.
|
||||
This tool appends information to the `## Gemini Added Memories` section of your
|
||||
global `GEMINI.md` file (typically located at `~/.gemini/GEMINI.md`).
|
||||
|
||||
### Arguments
|
||||
|
||||
`save_memory` takes one argument:
|
||||
|
||||
- `fact` (string, required): The specific fact or piece of information to
|
||||
remember. This should be a clear, self-contained statement written in natural
|
||||
- `fact` (string, required): A clear, self-contained statement in natural
|
||||
language.
|
||||
|
||||
## How to use `save_memory` with the Gemini CLI
|
||||
## Technical behavior
|
||||
|
||||
The tool appends the provided `fact` to a special `GEMINI.md` file located in
|
||||
the user's home directory (`~/.gemini/GEMINI.md`). This file can be configured
|
||||
to have a different name.
|
||||
- **Storage:** Appends to the global context file in the user's home directory.
|
||||
- **Loading:** The stored facts are automatically included in the hierarchical
|
||||
context system for all future sessions.
|
||||
- **Format:** Saves data as a bulleted list item within a dedicated Markdown
|
||||
section.
|
||||
|
||||
Once added, the facts are stored under a `## Gemini Added Memories` section.
|
||||
This file is loaded as context in subsequent sessions, allowing the CLI to
|
||||
recall the saved information.
|
||||
## Use cases
|
||||
|
||||
Usage:
|
||||
- Persisting user preferences (for example, "I prefer functional programming").
|
||||
- Saving project-wide architectural decisions.
|
||||
- Storing frequently used aliases or system configurations.
|
||||
|
||||
```
|
||||
save_memory(fact="Your fact here.")
|
||||
```
|
||||
## Next steps
|
||||
|
||||
### `save_memory` examples
|
||||
|
||||
Remember a user preference:
|
||||
|
||||
```
|
||||
save_memory(fact="My preferred programming language is Python.")
|
||||
```
|
||||
|
||||
Store a project-specific detail:
|
||||
|
||||
```
|
||||
save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **General usage:** This tool should be used for concise, important facts. It
|
||||
is not intended for storing large amounts of data or conversational history.
|
||||
- **Memory file:** The memory file is a plain text Markdown file, so you can
|
||||
view and edit it manually if needed.
|
||||
- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
|
||||
for practical examples.
|
||||
- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
|
||||
this information.
|
||||
|
||||
+39
-84
@@ -1,70 +1,33 @@
|
||||
# Shell tool (`run_shell_command`)
|
||||
|
||||
This document describes the `run_shell_command` tool for the Gemini CLI.
|
||||
The `run_shell_command` tool allows the Gemini model to execute commands
|
||||
directly on your system's shell. It is the primary mechanism for the agent to
|
||||
interact with your environment beyond simple file edits.
|
||||
|
||||
## Description
|
||||
## Technical reference
|
||||
|
||||
Use `run_shell_command` to interact with the underlying system, run scripts, or
|
||||
perform command-line operations. `run_shell_command` executes a given shell
|
||||
command, including interactive commands that require user input (e.g., `vim`,
|
||||
`git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to
|
||||
`true`.
|
||||
|
||||
On Windows, commands are executed with `powershell.exe -NoProfile -Command`
|
||||
(unless you explicitly point `ComSpec` at another shell). On other platforms,
|
||||
they are executed with `bash -c`.
|
||||
On Windows, commands execute with `powershell.exe -NoProfile -Command`. On other
|
||||
platforms, they execute with `bash -c`.
|
||||
|
||||
### Arguments
|
||||
|
||||
`run_shell_command` takes the following arguments:
|
||||
|
||||
- `command` (string, required): The exact shell command to execute.
|
||||
- `description` (string, optional): A brief description of the command's
|
||||
purpose, which will be shown to the user.
|
||||
- `directory` (string, optional): The directory (relative to the project root)
|
||||
in which to execute the command. If not provided, the command runs in the
|
||||
project root.
|
||||
- `description` (string, optional): A brief description shown to the user for
|
||||
confirmation.
|
||||
- `dir_path` (string, optional): The absolute path or relative path from
|
||||
workspace root where the command runs.
|
||||
- `is_background` (boolean, optional): Whether to move the process to the
|
||||
background immediately after starting.
|
||||
|
||||
## How to use `run_shell_command` with the Gemini CLI
|
||||
### Return values
|
||||
|
||||
When using `run_shell_command`, the command is executed as a subprocess.
|
||||
`run_shell_command` can start background processes using `&`. The tool returns
|
||||
detailed information about the execution, including:
|
||||
The tool returns a JSON object containing:
|
||||
|
||||
- `Command`: The command that was executed.
|
||||
- `Directory`: The directory where the command was run.
|
||||
- `Stdout`: Output from the standard output stream.
|
||||
- `Stderr`: Output from the standard error stream.
|
||||
- `Error`: Any error message reported by the subprocess.
|
||||
- `Exit Code`: The exit code of the command.
|
||||
- `Signal`: The signal number if the command was terminated by a signal.
|
||||
- `Background PIDs`: A list of PIDs for any background processes started.
|
||||
|
||||
Usage:
|
||||
|
||||
```
|
||||
run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")
|
||||
```
|
||||
|
||||
## `run_shell_command` examples
|
||||
|
||||
List files in the current directory:
|
||||
|
||||
```
|
||||
run_shell_command(command="ls -la")
|
||||
```
|
||||
|
||||
Run a script in a specific directory:
|
||||
|
||||
```
|
||||
run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
|
||||
```
|
||||
|
||||
Start a background server:
|
||||
|
||||
```
|
||||
run_shell_command(command="npm run dev &", description="Start development server in background")
|
||||
```
|
||||
- `Command`: The executed string.
|
||||
- `Directory`: The execution path.
|
||||
- `Stdout` / `Stderr`: The output streams.
|
||||
- `Exit Code`: The process return code.
|
||||
- `Background PIDs`: PIDs of any started background processes.
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -224,38 +187,30 @@ To block `rm` and allow all other commands:
|
||||
If a command prefix is in both `tools.core` and `tools.exclude`, it will be
|
||||
blocked.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"core": ["run_shell_command(git)"],
|
||||
"exclude": ["run_shell_command(git push)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
- **`tools.shell.enableInteractiveShell`**: (boolean) Uses `node-pty` for
|
||||
real-time interaction.
|
||||
- **`tools.shell.showColor`**: (boolean) Preserves ANSI colors in output.
|
||||
- **`tools.shell.inactivityTimeout`**: (number) Seconds to wait for output
|
||||
before killing the process.
|
||||
|
||||
- `git push origin main`: Blocked
|
||||
- `git status`: Allowed
|
||||
### Command restrictions
|
||||
|
||||
**Block all shell commands**
|
||||
You can limit which commands the agent is allowed to request using these
|
||||
settings:
|
||||
|
||||
To block all shell commands, add the `run_shell_command` wildcard to
|
||||
`tools.exclude`:
|
||||
- **`tools.core`**: An allowlist of command prefixes (for example,
|
||||
`["git", "npm test"]`).
|
||||
- **`tools.exclude`**: A blocklist of command prefixes.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"exclude": ["run_shell_command"]
|
||||
}
|
||||
}
|
||||
```
|
||||
## Use cases
|
||||
|
||||
- `ls -l`: Blocked
|
||||
- `any other command`: Blocked
|
||||
- Running build scripts and test suites.
|
||||
- Initializing or managing version control systems.
|
||||
- Installing project dependencies.
|
||||
- Starting development servers or background watchers.
|
||||
|
||||
## Security note for `excludeTools`
|
||||
## Next steps
|
||||
|
||||
Command-specific restrictions in `excludeTools` for `run_shell_command` are
|
||||
based on simple string matching and can be easily bypassed. This feature is
|
||||
**not a security mechanism** and should not be relied upon to safely execute
|
||||
untrusted code. It is recommended to use `coreTools` to explicitly select
|
||||
commands that can be executed.
|
||||
- Follow the [Shell commands tutorial](../cli/tutorials/shell-commands.md) for
|
||||
practical examples.
|
||||
- Learn about [Sandboxing](../cli/sandbox.md) to isolate command execution.
|
||||
|
||||
+22
-44
@@ -1,57 +1,35 @@
|
||||
# Todo tool (`write_todos`)
|
||||
|
||||
This document describes the `write_todos` tool for the Gemini CLI.
|
||||
The `write_todos` tool allows the Gemini agent to maintain an internal list of
|
||||
subtasks for multi-step requests.
|
||||
|
||||
## Description
|
||||
## Technical reference
|
||||
|
||||
The `write_todos` tool allows the Gemini agent to create and manage a list of
|
||||
subtasks for complex user requests. This provides you, the user, with greater
|
||||
visibility into the agent's plan and its current progress. It also helps with
|
||||
alignment where the agent is less likely to lose track of its current goal.
|
||||
The agent uses this tool to manage its execution plan and provide progress
|
||||
updates to the CLI interface.
|
||||
|
||||
### Arguments
|
||||
|
||||
`write_todos` takes one argument:
|
||||
- `todos` (array of objects, required): The complete list of tasks. Each object
|
||||
includes:
|
||||
- `description` (string): Technical description of the task.
|
||||
- `status` (enum): `pending`, `in_progress`, `completed`, or `cancelled`.
|
||||
|
||||
- `todos` (array of objects, required): The complete list of todo items. This
|
||||
replaces the existing list. Each item includes:
|
||||
- `description` (string): The task description.
|
||||
- `status` (string): The current status (`pending`, `in_progress`,
|
||||
`completed`, or `cancelled`).
|
||||
## Technical behavior
|
||||
|
||||
## Behavior
|
||||
- **Interface:** Updates the progress indicator above the CLI input prompt.
|
||||
- **Exclusivity:** Only one task can be marked `in_progress` at any time.
|
||||
- **Persistence:** Todo state is scoped to the current session.
|
||||
- **Interaction:** Users can toggle the full list view using **Ctrl+T**.
|
||||
|
||||
The agent uses this tool to break down complex multi-step requests into a clear
|
||||
plan.
|
||||
## Use cases
|
||||
|
||||
- **Progress tracking:** The agent updates this list as it works, marking tasks
|
||||
as `completed` when done.
|
||||
- **Single focus:** Only one task will be marked `in_progress` at a time,
|
||||
indicating exactly what the agent is currently working on.
|
||||
- **Dynamic updates:** The plan may evolve as the agent discovers new
|
||||
information, leading to new tasks being added or unnecessary ones being
|
||||
cancelled.
|
||||
- Breaking down a complex feature implementation into manageable steps.
|
||||
- Coordinating multi-file refactoring tasks.
|
||||
- Providing visibility into the agent's current focus during long-running tasks.
|
||||
|
||||
When active, the current `in_progress` task is displayed above the input box,
|
||||
keeping you informed of the immediate action. You can toggle the full view of
|
||||
the todo list at any time by pressing `Ctrl+T`.
|
||||
## Next steps
|
||||
|
||||
Usage example (internal representation):
|
||||
|
||||
```javascript
|
||||
write_todos({
|
||||
todos: [
|
||||
{ description: 'Initialize new React project', status: 'completed' },
|
||||
{ description: 'Implement state management', status: 'in_progress' },
|
||||
{ description: 'Create API service', status: 'pending' },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Enabling:** This tool is enabled by default. You can disable it in your
|
||||
`settings.json` file by setting `"useWriteTodos": false`.
|
||||
|
||||
- **Intended use:** This tool is primarily used by the agent for complex,
|
||||
multi-turn tasks. It is generally not used for simple, single-turn questions.
|
||||
- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
|
||||
usage details.
|
||||
- Learn about [Session management](../cli/session-management.md) for context.
|
||||
|
||||
+22
-46
@@ -1,59 +1,35 @@
|
||||
# Web fetch tool (`web_fetch`)
|
||||
|
||||
This document describes the `web_fetch` tool for the Gemini CLI.
|
||||
The `web_fetch` tool allows the Gemini agent to retrieve and process content
|
||||
from specific URLs provided in your prompt.
|
||||
|
||||
## Description
|
||||
## Technical reference
|
||||
|
||||
Use `web_fetch` to summarize, compare, or extract information from web pages.
|
||||
The `web_fetch` tool processes content from one or more URLs (up to 20) embedded
|
||||
in a prompt. `web_fetch` takes a natural language prompt and returns a generated
|
||||
response.
|
||||
The agent uses this tool when you include URLs in your prompt and request
|
||||
specific operations like summarization or extraction.
|
||||
|
||||
### Arguments
|
||||
|
||||
`web_fetch` takes one argument:
|
||||
- `prompt` (string, required): A request containing up to 20 valid URLs
|
||||
(starting with `http://` or `https://`) and instructions on how to process
|
||||
them.
|
||||
|
||||
- `prompt` (string, required): A comprehensive prompt that includes the URL(s)
|
||||
(up to 20) to fetch and specific instructions on how to process their content.
|
||||
For example:
|
||||
`"Summarize https://example.com/article and extract key points from https://another.com/data"`.
|
||||
The prompt must contain at least one URL starting with `http://` or
|
||||
`https://`.
|
||||
## Technical behavior
|
||||
|
||||
## How to use `web_fetch` with the Gemini CLI
|
||||
- **Confirmation:** Triggers a confirmation dialog showing the converted URLs.
|
||||
- **Processing:** Uses the Gemini API's `urlContext` for retrieval.
|
||||
- **Fallback:** If API access fails, the tool attempts to fetch raw content
|
||||
directly from your local machine.
|
||||
- **Formatting:** Returns a synthesized response with source attribution.
|
||||
|
||||
To use `web_fetch` with the Gemini CLI, provide a natural language prompt that
|
||||
contains URLs. The tool will ask for confirmation before fetching any URLs. Once
|
||||
confirmed, the tool will process URLs through Gemini API's `urlContext`.
|
||||
## Use cases
|
||||
|
||||
If the Gemini API cannot access the URL, the tool will fall back to fetching
|
||||
content directly from the local machine. The tool will format the response,
|
||||
including source attribution and citations where possible. The tool will then
|
||||
provide the response to the user.
|
||||
- Summarizing technical articles or blog posts.
|
||||
- Comparing data between two or more web pages.
|
||||
- Extracting specific information from a documentation site.
|
||||
|
||||
Usage:
|
||||
## Next steps
|
||||
|
||||
```
|
||||
web_fetch(prompt="Your prompt, including a URL such as https://google.com.")
|
||||
```
|
||||
|
||||
## `web_fetch` examples
|
||||
|
||||
Summarize a single article:
|
||||
|
||||
```
|
||||
web_fetch(prompt="Can you summarize the main points of https://example.com/news/latest")
|
||||
```
|
||||
|
||||
Compare two articles:
|
||||
|
||||
```
|
||||
web_fetch(prompt="What are the differences in the conclusions of these two papers: https://arxiv.org/abs/2401.0001 and https://arxiv.org/abs/2401.0002?")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **URL processing:** `web_fetch` relies on the Gemini API's ability to access
|
||||
and process the given URLs.
|
||||
- **Output quality:** The quality of the output will depend on the clarity of
|
||||
the instructions in the prompt.
|
||||
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
|
||||
usage examples.
|
||||
- See the [Web search tool reference](./web-search.md) for general queries.
|
||||
|
||||
+19
-29
@@ -1,42 +1,32 @@
|
||||
# Web search tool (`google_web_search`)
|
||||
|
||||
This document describes the `google_web_search` tool.
|
||||
The `google_web_search` tool allows the Gemini agent to retrieve up-to-date
|
||||
information, news, and facts from the internet via Google Search.
|
||||
|
||||
## Description
|
||||
## Technical reference
|
||||
|
||||
Use `google_web_search` to perform a web search using Google Search via the
|
||||
Gemini API. The `google_web_search` tool returns a summary of web results with
|
||||
sources.
|
||||
The agent uses this tool when your request requires knowledge of current events
|
||||
or specific online documentation not available in its internal training data.
|
||||
|
||||
### Arguments
|
||||
|
||||
`google_web_search` takes one argument:
|
||||
- `query` (string, required): The search query to be executed.
|
||||
|
||||
- `query` (string, required): The search query.
|
||||
## Technical behavior
|
||||
|
||||
## How to use `google_web_search` with the Gemini CLI
|
||||
- **Grounding:** Returns a generated summary based on search results.
|
||||
- **Citations:** Includes source URIs and titles for factual grounding.
|
||||
- **Processing:** The Gemini API processes the search results before returning a
|
||||
synthesized response to the agent.
|
||||
|
||||
The `google_web_search` tool sends a query to the Gemini API, which then
|
||||
performs a web search. `google_web_search` will return a generated response
|
||||
based on the search results, including citations and sources.
|
||||
## Use cases
|
||||
|
||||
Usage:
|
||||
- Researching the latest version of a software library or API.
|
||||
- Finding solutions to recent software bugs or security vulnerabilities.
|
||||
- Retrieving news or documentation updated after the model's knowledge cutoff.
|
||||
|
||||
```
|
||||
google_web_search(query="Your query goes here.")
|
||||
```
|
||||
## Next steps
|
||||
|
||||
## `google_web_search` examples
|
||||
|
||||
Get information on a topic:
|
||||
|
||||
```
|
||||
google_web_search(query="latest advancements in AI-powered code generation")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Response returned:** The `google_web_search` tool returns a processed
|
||||
summary, not a raw list of search results.
|
||||
- **Citations:** The response includes citations to the sources used to generate
|
||||
the summary.
|
||||
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
|
||||
usage examples.
|
||||
- Explore the [Web fetch tool reference](./web-fetch.md) for direct URL access.
|
||||
|
||||
Reference in New Issue
Block a user