chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,284 @@
|
||||
# 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 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 -p "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:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
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 -p "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` (or `generate_docs.ps1` for
|
||||
Windows):
|
||||
|
||||
**macOS/Linux (`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 -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.
|
||||
|
||||
## 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` (or `generate_json.ps1` for
|
||||
Windows):
|
||||
|
||||
**macOS/Linux (`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
|
||||
```
|
||||
|
||||
**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
|
||||
{
|
||||
"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 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.
|
||||
|
||||
```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 -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:
|
||||
|
||||
```bash
|
||||
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
|
||||
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,144 @@
|
||||
# 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 (for example, a git repository).
|
||||
|
||||
## 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,
|
||||
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 (for example,
|
||||
`src/components/UserProfile.tsx`), which you can then use with `@` in your next
|
||||
turn.
|
||||
|
||||
<!-- 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
|
||||
|
||||
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 (for
|
||||
example, `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,115 @@
|
||||
# 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:
|
||||
|
||||
**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`.
|
||||
|
||||
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/github/github-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<!-- 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
|
||||
|
||||
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 `mcp_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 (for example, "image not found").
|
||||
- **Tools not found?** Run `/mcp reload` 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,128 @@
|
||||
# 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?
|
||||
|
||||
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.
|
||||
|
||||
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 lets you 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 edit the appropriate memory Markdown file, so the fact is loaded
|
||||
in future sessions.
|
||||
|
||||
**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 reload`
|
||||
|
||||
## Best practices
|
||||
|
||||
- **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
|
||||
(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.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn about [Session management](session-management.md) to see how short-term
|
||||
history works.
|
||||
- Explore the [Command reference](../../reference/commands.md) for more
|
||||
`/memory` options.
|
||||
- Read the technical spec for [Project context](../../cli/gemini-md.md).
|
||||
- Try the experimental [Auto Memory](../auto-memory.md) feature to extract
|
||||
memory updates and reusable skills from your past sessions automatically.
|
||||
@@ -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 (for example, "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.
|
||||
@@ -0,0 +1,118 @@
|
||||
# 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 (for example, "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
|
||||
```
|
||||
|
||||
### Scenario: Delete session on exit
|
||||
|
||||
If you're doing a one-off task and don't want to leave any session history
|
||||
behind, use the `--delete` flag when exiting:
|
||||
|
||||
```
|
||||
/exit --delete
|
||||
```
|
||||
|
||||
This removes the current session's conversation history and tool output files
|
||||
before exiting. It's useful for privacy-sensitive tasks or quick one-off
|
||||
interactions.
|
||||
|
||||
## 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 `/resume save decision-point`.
|
||||
3. Try your first approach.
|
||||
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.
|
||||
|
||||
## 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](../../reference/commands.md) for `/resume`
|
||||
options, grouped checkpoint menus, and `/chat` compatibility aliases.
|
||||
@@ -0,0 +1,108 @@
|
||||
# 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, and so on).
|
||||
|
||||
## 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.
|
||||
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
|
||||
|
||||
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 lets Gemini work autonomously.
|
||||
|
||||
## 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 (for example, `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 features
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,158 @@
|
||||
# Get started with Agent Skills
|
||||
|
||||
Agent Skills extend Gemini CLI with specialized expertise. In this tutorial,
|
||||
you'll learn how to create your first skill, bundle custom logic, and activate
|
||||
it during a session.
|
||||
|
||||
## Create your first skill
|
||||
|
||||
A skill is defined by a directory containing a `SKILL.md` file and
|
||||
subdirectories containing reference materials or scripts used by the skill.
|
||||
Let's create an **API Auditor** skill that runs a script to help you verify if
|
||||
local or remote endpoints are responding correctly.
|
||||
|
||||
### 1. Create the directory structure
|
||||
|
||||
The first step is to create the necessary folders for your skill and its
|
||||
scripts.
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
mkdir -p .gemini/skills/api-auditor/scripts
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Directory -Force -Path ".gemini\skills\api-auditor\scripts"
|
||||
```
|
||||
|
||||
### 2. Create the definition (`SKILL.md`)
|
||||
|
||||
The `SKILL.md` file defines the skill's purpose and instructions for the agent.
|
||||
Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent
|
||||
_when_ to use the skill and _how_ to behave.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: api-auditor
|
||||
description:
|
||||
Expertise in auditing and testing API endpoints. Use when the user asks to
|
||||
"check", "test", or "audit" a URL or API.
|
||||
---
|
||||
|
||||
# API Auditor Instructions
|
||||
|
||||
You act as a QA engineer specialized in API reliability. When this skill is
|
||||
active, you MUST:
|
||||
|
||||
1. **Audit**: Use the bundled `scripts/audit.js` utility to check the status of
|
||||
the provided URL.
|
||||
2. **Report**: Analyze the output (status codes, latency) and explain any
|
||||
failures in plain English.
|
||||
3. **Secure**: Remind the user if they are testing a sensitive endpoint without
|
||||
an `https://` protocol.
|
||||
```
|
||||
|
||||
### 3. Add the tool logic
|
||||
|
||||
Skills can bundle resources like scripts to perform deterministic tasks. 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
|
||||
const url = process.argv[2];
|
||||
|
||||
if (!url) {
|
||||
console.error('Usage: node audit.js <url>');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`Auditing ${url}...`);
|
||||
fetch(url, { method: 'HEAD' })
|
||||
.then((r) => console.log(`Result: Success (Status ${r.status})`))
|
||||
.catch((e) => console.error(`Result: Failed (${e.message})`));
|
||||
```
|
||||
|
||||
## Verify discovery
|
||||
|
||||
Gemini CLI automatically discovers skills in the `.gemini/skills` directory (as
|
||||
well as the `.agents/skills` alias).
|
||||
|
||||
To check if Gemini CLI found your new skill, use the `/skills list` command
|
||||
within an interactive session:
|
||||
|
||||
```bash
|
||||
/skills list
|
||||
```
|
||||
|
||||
You should see `api-auditor` in the list of available skills. If you just added
|
||||
the files, you can run `/skills reload` to refresh the list without restarting
|
||||
the session.
|
||||
|
||||
### If your skill doesn't appear
|
||||
|
||||
If `/skills list` doesn't show your skill, check the following:
|
||||
|
||||
1. **The folder must be trusted (workspace skills only).** Skills under
|
||||
`<workspace>/.gemini/skills/` are only loaded when the workspace folder is
|
||||
marked as trusted. Run `/trust` and restart the session if needed. Skills
|
||||
under `~/.gemini/skills/` (user scope) are not affected by trust.
|
||||
2. **Check the path layout.** `SKILL.md` is discovered either at the root of
|
||||
the skills directory (`.gemini/skills/SKILL.md`) or one directory deep
|
||||
(`.gemini/skills/<skill-name>/SKILL.md`). The recommended layout uses a
|
||||
subdirectory per skill so you can bundle scripts and other resources
|
||||
alongside it. Files nested more than one directory deep are not discovered.
|
||||
3. **The filename must be exactly `SKILL.md`.** Capitalization matters on
|
||||
case-sensitive filesystems (Linux, and macOS when configured as such):
|
||||
`skill.md` or `Skill.md` will be ignored.
|
||||
4. **Frontmatter must include both `name:` and `description:`, and must be the
|
||||
first thing in the file.** A `SKILL.md` is silently skipped if either field
|
||||
is missing, if the delimiters (`---` on their own lines) are absent, or if
|
||||
any text (an H1 title, a comment, even a blank line) appears before the
|
||||
opening `---`.
|
||||
5. **The skill name comes from the `name:` field, not the directory name.** If
|
||||
your frontmatter says `name: foo`, the skill appears as `foo` in
|
||||
`/skills list` regardless of what its parent directory is called. The
|
||||
characters `: \ / < > * ? " |` in the name are replaced with `-`.
|
||||
|
||||
## How to use the skill
|
||||
|
||||
Now that the skill is discovered, you can trigger its activation by asking a
|
||||
relevant question.
|
||||
|
||||
1. **Trigger**: Start a new session and ask: "Can you audit https://google.com"
|
||||
2. **Activation**: Gemini identifies that the request matches the `api-auditor`
|
||||
description and calls the `activate_skill` tool.
|
||||
3. **Consent**: You will see a confirmation prompt. Type **y** to approve.
|
||||
4. **Execution**: Once activated, Gemini uses the `run_shell_command` tool to
|
||||
execute your bundled script:
|
||||
`node .gemini/skills/api-auditor/scripts/audit.js https://google.com`
|
||||
|
||||
## Pro tip: Use the skill-creator
|
||||
|
||||
If you don't want to create the files manually, you can use the built-in
|
||||
`skill-creator` skill. Simply ask Gemini:
|
||||
|
||||
> "Create a new skill called 'api-auditor' that tests if URLs are responding."
|
||||
|
||||
The `skill-creator` will handle the directory structure and boilerplate for you.
|
||||
|
||||
## Manage skills
|
||||
|
||||
You can also manage skills using the `gemini skills` command from your terminal:
|
||||
|
||||
- **Install**: `gemini skills install <url-or-path>`
|
||||
- **Link**: `gemini skills link <path>` (useful for local development)
|
||||
- **Uninstall**: `gemini skills uninstall <name>`
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Creating Agent Skills](../creating-skills.md): Detailed guide on advanced
|
||||
skill features and metadata.
|
||||
- [Using Agent Skills](../using-agent-skills.md): More ways to discover and
|
||||
manage your skill library.
|
||||
- [Skill best practices](../skills-best-practices.md): Learn how to design
|
||||
reliable and effective expertise.
|
||||
@@ -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 (for example, 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 (for example,
|
||||
`[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 (for example, "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.
|
||||
Reference in New Issue
Block a user