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

Docs: Refresh docs to organize and standardize reference materials. (#18403)

Browse Source
This commit is contained in:
Jenna Inouye
2026-02-13 14:09:17 -08:00
committed by GitHub
parent f76e24c00f
commit c7237f0c79
37 changed files with 2343 additions and 1676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/cli/tutorials/automation.md Normal file
View File

@@ -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.

142
docs/cli/tutorials/file-management.md Normal file
View File

@@ -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.

105
docs/cli/tutorials/mcp-setup.md Normal file
View File

@@ -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.

126
docs/cli/tutorials/memory-management.md Normal file
View File

@@ -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).

105
docs/cli/tutorials/session-management.md Normal file
View File

@@ -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.

107
docs/cli/tutorials/shell-commands.md Normal file
View File

@@ -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.

66
docs/cli/tutorials/skills-getting-started.md
View File

@@ -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).

93
docs/cli/tutorials/task-planning.md Normal file
View File

@@ -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").

78
docs/cli/tutorials/web-tools.md Normal file
View File

@@ -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.