mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-05-18 07:43:00 -07:00
Merge remote-tracking branch 'origin/main' into gemini-cli-resume-minimal
# Conflicts: # docs/cli/cli-reference.md # packages/cli/src/gemini.test.tsx # packages/cli/src/ui/AppContainer.tsx # packages/cli/src/ui/components/DialogManager.tsx # packages/cli/src/ui/components/SessionBrowser.tsx # packages/cli/src/ui/components/SessionSummaryDisplay.test.tsx # packages/cli/src/ui/components/SessionSummaryDisplay.tsx # packages/cli/src/ui/components/__snapshots__/SessionSummaryDisplay.test.tsx.snap # packages/cli/src/ui/hooks/useSessionBrowser.test.ts # packages/cli/src/ui/hooks/useSessionResume.test.ts # packages/cli/src/utils/sessionUtils.test.ts # packages/cli/src/utils/sessionUtils.ts # packages/core/src/services/chatRecordingService.ts
This commit is contained in:
Dmitry Lyalin
@@ -19,14 +19,15 @@ Headless mode runs Gemini CLI once and exits. It's perfect for:
|
||||
|
||||
## 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 Gemini CLI in headless mode by providing a prompt with the `-p` (or
|
||||
`--prompt`) flag. This bypasses the interactive chat interface and prints the
|
||||
response to standard output (stdout). Positional arguments without the flag
|
||||
default to interactive mode, unless the input or output is piped or redirected.
|
||||
|
||||
Run a single command:
|
||||
|
||||
```bash
|
||||
gemini "Write a poem about TypeScript"
|
||||
gemini -p "Write a poem about TypeScript"
|
||||
```
|
||||
|
||||
## How to pipe input to Gemini CLI
|
||||
@@ -37,14 +38,22 @@ output.
|
||||
|
||||
Pipe a file:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
cat error.log | gemini "Explain why this failed"
|
||||
cat error.log | gemini -p "Explain why this failed"
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
Get-Content error.log | gemini -p "Explain why this failed"
|
||||
```
|
||||
|
||||
Pipe a command:
|
||||
|
||||
```bash
|
||||
git diff | gemini "Write a commit message for these changes"
|
||||
git diff | gemini -p "Write a commit message for these changes"
|
||||
```
|
||||
|
||||
## Use Gemini CLI output in scripts
|
||||
@@ -57,7 +66,10 @@ results to a file.
|
||||
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`:
|
||||
1. Save the following code as `generate_docs.sh` (or `generate_docs.ps1` for
|
||||
Windows):
|
||||
|
||||
**macOS/Linux (`generate_docs.sh`)**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
@@ -67,18 +79,39 @@ one.
|
||||
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
|
||||
gemini -p "Generate a Markdown documentation summary for @$file. Print the
|
||||
result to standard output." > "${file%.py}.md"
|
||||
done
|
||||
```
|
||||
|
||||
**Windows PowerShell (`generate_docs.ps1`)**
|
||||
|
||||
```powershell
|
||||
# Loop through all Python files
|
||||
Get-ChildItem -Filter *.py | ForEach-Object {
|
||||
Write-Host "Generating docs for $($_.Name)..."
|
||||
|
||||
$newName = $_.Name -replace '\.py$', '.md'
|
||||
# Ask Gemini CLI to generate the documentation and print it to stdout
|
||||
gemini -p "Generate a Markdown documentation summary for @$($_.Name). Print the result to standard output." | Out-File -FilePath $newName -Encoding utf8
|
||||
}
|
||||
```
|
||||
|
||||
2. Make the script executable and run it in your directory:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
chmod +x generate_docs.sh
|
||||
./generate_docs.sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
.\generate_docs.ps1
|
||||
```
|
||||
|
||||
This creates a corresponding Markdown file for every Python file in the
|
||||
folder.
|
||||
|
||||
@@ -90,7 +123,10 @@ like `jq`. To get pure JSON data from the model, combine the
|
||||
|
||||
### Scenario: Extract and return structured data
|
||||
|
||||
1. Save the following script as `generate_json.sh`:
|
||||
1. Save the following script as `generate_json.sh` (or `generate_json.ps1` for
|
||||
Windows):
|
||||
|
||||
**macOS/Linux (`generate_json.sh`)**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
@@ -105,13 +141,35 @@ like `jq`. To get pure JSON data from the model, combine the
|
||||
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`:
|
||||
**Windows PowerShell (`generate_json.ps1`)**
|
||||
|
||||
```powershell
|
||||
# Ensure we are in a project root
|
||||
if (-not (Test-Path "package.json")) {
|
||||
Write-Error "Error: package.json not found."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Extract data (requires jq installed, or you can use ConvertFrom-Json)
|
||||
$output = gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | ConvertFrom-Json
|
||||
$output.response | Out-File -FilePath data.json -Encoding utf8
|
||||
```
|
||||
|
||||
2. Run the script:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
chmod +x generate_json.sh
|
||||
./generate_json.sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
.\generate_json.ps1
|
||||
```
|
||||
|
||||
3. Check `data.json`. The file should look like this:
|
||||
|
||||
```json
|
||||
@@ -129,8 +187,10 @@ 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.
|
||||
You can add a function to your shell configuration to create a `git commit`
|
||||
wrapper that writes the message for you.
|
||||
|
||||
**macOS/Linux (Bash/Zsh)**
|
||||
|
||||
1. Open your `.zshrc` file (or `.bashrc` if you use Bash) in your preferred
|
||||
text editor.
|
||||
@@ -155,7 +215,7 @@ to create a `git commit` wrapper that writes the message for you.
|
||||
|
||||
# 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.")
|
||||
msg=$(echo "$diff" | gemini -p "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
|
||||
|
||||
# Commit with the generated message
|
||||
git commit -m "$msg"
|
||||
@@ -170,6 +230,43 @@ to create a `git commit` wrapper that writes the message for you.
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
1. Open your PowerShell profile in your preferred text editor.
|
||||
|
||||
```powershell
|
||||
notepad $PROFILE
|
||||
```
|
||||
|
||||
2. Scroll to the very bottom of the file and paste this code:
|
||||
|
||||
```powershell
|
||||
function gcommit {
|
||||
# Get the diff of staged changes
|
||||
$diff = git diff --staged
|
||||
|
||||
if (-not $diff) {
|
||||
Write-Host "No staged changes to commit."
|
||||
return
|
||||
}
|
||||
|
||||
# Ask Gemini to write the message
|
||||
Write-Host "Generating commit message..."
|
||||
$msg = $diff | gemini -p "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:
|
||||
|
||||
```powershell
|
||||
. $PROFILE
|
||||
```
|
||||
|
||||
4. Use your new command:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -7,9 +7,9 @@ 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).
|
||||
- A project directory to work with (for example, a git repository).
|
||||
|
||||
## How to give the agent context (Reading files)
|
||||
## Providing context by 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,
|
||||
@@ -58,11 +58,13 @@ You know there's a `UserProfile` component, but you don't know where it lives.
|
||||
```
|
||||
|
||||
Gemini uses the `glob` or `list_directory` tools to search your project
|
||||
structure. It will return the specific path (e.g.,
|
||||
structure. It will return the specific path (for example,
|
||||
`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
|
||||
<!-- prettier-ignore -->
|
||||
> [!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
|
||||
@@ -111,8 +113,8 @@ or, better yet, run your project's tests.
|
||||
`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
|
||||
Gemini CLI uses the `run_shell_command` tool to execute your test runner (for
|
||||
example, `npm test` or `jest`). This ensures the changes didn't break existing
|
||||
functionality.
|
||||
|
||||
## Advanced: Controlling what Gemini sees
|
||||
|
||||
@@ -20,10 +20,18 @@ Most MCP servers require authentication. For GitHub, you need a PAT.
|
||||
**Read/Write** access to **Issues** and **Pull Requests**.
|
||||
3. Store it in your environment:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
$env:GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."
|
||||
```
|
||||
|
||||
## How to configure Gemini CLI
|
||||
|
||||
You tell Gemini about new servers by editing your `settings.json`.
|
||||
@@ -44,7 +52,7 @@ You tell Gemini about new servers by editing your `settings.json`.
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/modelcontextprotocol/servers/github:latest"
|
||||
"ghcr.io/github/github-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
@@ -54,8 +62,10 @@ You tell Gemini about new servers by editing your `settings.json`.
|
||||
}
|
||||
```
|
||||
|
||||
> **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
|
||||
<!-- prettier-ignore -->
|
||||
> [!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
|
||||
@@ -81,7 +91,7 @@ don't need to learn special commands; just ask in natural language.
|
||||
The agent will:
|
||||
|
||||
1. Recognize the request matches a GitHub tool.
|
||||
2. Call `github_list_pull_requests`.
|
||||
2. Call `mcp_github_list_pull_requests`.
|
||||
3. Present the data to you.
|
||||
|
||||
### Scenario: Creating an issue
|
||||
@@ -93,8 +103,8 @@ The agent will:
|
||||
|
||||
- **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.
|
||||
- **Tools not found?** Run `/mcp reload` to force the CLI to re-query the server
|
||||
for its capabilities.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -11,8 +11,8 @@ persistent facts, and inspect the active context.
|
||||
|
||||
## 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
|
||||
Gemini CLI is powerful but general. It doesn't know your preferred testing
|
||||
framework, your indentation style, or your preference against `any` in
|
||||
TypeScript. Context management solves this by giving the agent persistent
|
||||
memory.
|
||||
|
||||
@@ -105,15 +105,15 @@ excellent for debugging why the agent might be ignoring a rule.
|
||||
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`
|
||||
**Command:** `/memory reload`
|
||||
|
||||
## Best practices
|
||||
|
||||
- **Keep it focused:** Don't dump your entire internal wiki into `GEMINI.md`.
|
||||
Keep instructions actionable and relevant to code generation.
|
||||
- **Keep it focused:** Avoid adding excessive content to `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.
|
||||
(for example, "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.
|
||||
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Use Plan Mode with model steering for complex tasks
|
||||
|
||||
Architecting a complex solution requires precision. By combining Plan Mode's
|
||||
structured environment with model steering's real-time feedback, you can guide
|
||||
Gemini CLI through the research and design phases to ensure the final
|
||||
implementation plan is exactly what you need.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
> [!NOTE]
|
||||
> This is an experimental feature currently under active development and
|
||||
> may need to be enabled under `/settings`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Gemini CLI installed and authenticated.
|
||||
- [Plan Mode](../plan-mode.md) enabled in your settings.
|
||||
- [Model steering](../model-steering.md) enabled in your settings.
|
||||
|
||||
## Why combine Plan Mode and model steering?
|
||||
|
||||
[Plan Mode](../plan-mode.md) typically follows a linear path: research, propose,
|
||||
and draft. Adding model steering lets you:
|
||||
|
||||
1. **Direct the research:** Correct the agent if it's looking in the wrong
|
||||
directory or missing a key dependency.
|
||||
2. **Iterate mid-draft:** Suggest a different architectural pattern while the
|
||||
agent is still writing the plan.
|
||||
3. **Speed up the loop:** Avoid waiting for a full research turn to finish
|
||||
before providing critical context.
|
||||
|
||||
## Step 1: Start a complex task
|
||||
|
||||
Enter Plan Mode and start a task that requires research.
|
||||
|
||||
**Prompt:** `/plan I want to implement a new notification service using Redis.`
|
||||
|
||||
Gemini CLI enters Plan Mode and starts researching your existing codebase to
|
||||
identify where the new service should live.
|
||||
|
||||
## Step 2: Steer the research phase
|
||||
|
||||
As you see the agent calling tools like `list_directory` or `grep_search`, you
|
||||
might realize it's missing the relevant context.
|
||||
|
||||
**Action:** While the spinner is active, type your hint:
|
||||
`"Don't forget to check packages/common/queues for the existing Redis config."`
|
||||
|
||||
**Result:** Gemini CLI acknowledges your hint and immediately incorporates it
|
||||
into its research. You'll see it start exploring the directory you suggested in
|
||||
its very next turn.
|
||||
|
||||
## Step 3: Refine the design mid-turn
|
||||
|
||||
After research, the agent starts drafting the implementation plan. If you notice
|
||||
it's proposing a design that doesn't align with your goals, steer it.
|
||||
|
||||
**Action:** Type:
|
||||
`"Actually, let's use a Publisher/Subscriber pattern instead of a simple queue for this service."`
|
||||
|
||||
**Result:** The agent stops drafting the current version of the plan,
|
||||
re-evaluates the design based on your feedback, and starts a new draft that uses
|
||||
the Pub/Sub pattern.
|
||||
|
||||
## Step 4: Approve and implement
|
||||
|
||||
Once the agent has used your hints to craft the perfect plan, review the final
|
||||
`.md` file.
|
||||
|
||||
**Action:** Type: `"Looks perfect. Let's start the implementation."`
|
||||
|
||||
Gemini CLI exits Plan Mode and transitions to the implementation phase. Because
|
||||
the plan was refined in real-time with your feedback, the agent can now execute
|
||||
each step with higher confidence and fewer errors.
|
||||
|
||||
## Tips for effective steering
|
||||
|
||||
- **Be specific:** Instead of "do it differently," try "use the existing
|
||||
`Logger` class in `src/utils`."
|
||||
- **Steer early:** Providing feedback during the research phase is more
|
||||
efficient than waiting for the final plan to be drafted.
|
||||
- **Use for context:** Steering is a great way to provide knowledge that might
|
||||
not be obvious from reading the code (e.g., "We are planning to deprecate this
|
||||
module next month").
|
||||
|
||||
## Next steps
|
||||
|
||||
- Explore [Agent Skills](../skills.md) to add specialized expertise to your
|
||||
planning turns.
|
||||
- See the [Model steering reference](../model-steering.md) for technical
|
||||
details.
|
||||
@@ -104,9 +104,9 @@ Gemini gives you granular control over the undo process. You can choose to:
|
||||
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`.
|
||||
2. Save the current state with `/resume save decision-point`.
|
||||
3. Try your first approach.
|
||||
4. Later, use `/chat resume decision-point` to fork the conversation back to
|
||||
4. Later, use `/resume 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.
|
||||
@@ -116,5 +116,5 @@ This creates a new branch of history without losing your original work.
|
||||
- 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](../../reference/commands.md) for all `/chat` and
|
||||
`/resume` options.
|
||||
- See the [Command reference](../../reference/commands.md) for `/resume`
|
||||
options, grouped checkpoint menus, and `/chat` compatibility aliases.
|
||||
|
||||
@@ -7,7 +7,7 @@ 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.).
|
||||
- Basic familiarity with your system's shell (Bash, Zsh, PowerShell, and so on).
|
||||
|
||||
## How to run commands directly (`!`)
|
||||
|
||||
@@ -17,9 +17,10 @@ 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.
|
||||
This executes `ls -la` immediately and prints the output to your terminal.
|
||||
Gemini CLI also records the command and its output in the current session
|
||||
context, so the model can reference it in follow-up prompts. Very large outputs
|
||||
may be truncated.
|
||||
|
||||
### Scenario: Entering Shell mode
|
||||
|
||||
@@ -48,7 +49,7 @@ You want to run tests and fix any failures.
|
||||
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.
|
||||
This loop lets Gemini work autonomously.
|
||||
|
||||
## How to manage background processes
|
||||
|
||||
@@ -74,7 +75,7 @@ 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
|
||||
## Safety features
|
||||
|
||||
Giving an AI access to your shell is powerful but risky. Gemini CLI includes
|
||||
several safety layers.
|
||||
|
||||
@@ -14,10 +14,18 @@ responding correctly.
|
||||
|
||||
1. Run the following command to create the folders:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
mkdir -p .gemini/skills/api-auditor/scripts
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Directory -Force -Path ".gemini\skills\api-auditor\scripts"
|
||||
```
|
||||
|
||||
### Create the definition
|
||||
|
||||
1. Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent
|
||||
|
||||
Reference in New Issue
Block a user