llms.txt
Compare with other sites' llms.txt files →# Gemini CLI Documentation
# [Automation and triage processes](http://geminicli.com/docs/issue-and-pr-automation.md)
This document provides a detailed overview of the automated processes we use to
manage and triage issues and pull requests. Our goal is to provide prompt
feedback and ensure that contributions are reviewed and integrated efficiently.
Understanding this automation will help you as a contributor know what to expect
and how to best interact with our repository bots.
## Guiding principle: Issues and pull requests
First and foremost, almost every Pull Request (PR) should be linked to a
corresponding Issue. The issue describes the "what" and the "why" (the bug or
feature), while the PR is the "how" (the implementation). This separation helps
us track work, prioritize features, and maintain clear historical context. Our
automation is built around this principle.
<!-- prettier-ignore -->
> [!NOTE]
> Issues tagged as "🔒Maintainers only" are reserved for project
> maintainers. We will not accept pull requests related to these issues.
---
## Detailed automation workflows
Here is a breakdown of the specific automation workflows that run in our
repository.
### 1. When you open an issue: `Automated Issue Triage`
This is the first bot you will interact with when you create an issue. Its job
is to perform an initial analysis and apply the correct labels.
- **Workflow File**: `.github/workflows/gemini-automated-issue-triage.yml`
- **When it runs**: Immediately after an issue is created or reopened.
- **What it does**:
- It uses a Gemini model to analyze the issue's title and body against a
detailed set of guidelines.
- **Applies one `area/*` label**: Categorizes the issue into a functional area
of the project (for example, `area/ux`, `area/models`, `area/platform`).
- **Applies one `kind/*` label**: Identifies the type of issue (for example,
`kind/bug`, `kind/enhancement`, `kind/question`).
- **Applies one `priority/*` label**: Assigns a priority from P0 (critical) to
P3 (low) based on the described impact.
- **May apply `status/need-information`**: If the issue lacks critical details
(like logs or reproduction steps), it will be flagged for more information.
- **May apply `status/need-retesting`**: If the issue references a CLI version
that is more than six versions old, it will be flagged for retesting on a
current version.
- **What you should do**:
- Fill out the issue template as completely as possible. The more detail you
provide, the more accurate the triage will be.
- If the `status/need-information` label is added, provide the requested
details in a comment.
### 2. When you open a pull request: `Continuous Integration (CI)`
This workflow ensures that all changes meet our quality standards before they
can be merged.
- **Workflow File**: `.github/workflows/ci.yml`
- **When it runs**: On every push to a pull request.
- **What it does**:
- **Lint**: Checks that your code adheres to our project's formatting and
style rules.
- **Test**: Runs our full suite of automated tests across macOS, Windows, and
Linux, and on multiple Node.js versions. This is the most time-consuming
part of the CI process.
- **Post Coverage Comment**: After all tests have successfully passed, a bot
will post a comment on your PR. This comment provides a summary of how well
your changes are covered by tests.
- **What you should do**:
- Ensure all CI checks pass. A green checkmark ✅ will appear next to your
commit when everything is successful.
- If a check fails (a red "X" ❌), click the "Details" link next to the failed
check to view the logs, identify the problem, and push a fix.
### 3. Ongoing triage for pull requests: `PR Auditing and Label Sync`
This workflow runs periodically to ensure all open PRs are correctly linked to
issues and have consistent labels.
- **Workflow File**: `.github/workflows/gemini-scheduled-pr-triage.yml`
- **When it runs**: Every 15 minutes on all open pull requests.
- **What it does**:
- **Checks for a linked issue**: The bot scans your PR description for a
keyword that links it to an issue (for example, `Fixes #123`,
`Closes #456`).
- **Adds `status/need-issue`**: If no linked issue is found, the bot will add
the `status/need-issue` label to your PR. This is a clear signal that an
issue needs to be created and linked.
- **Synchronizes labels**: If an issue _is_ linked, the bot ensures the PR's
labels perfectly match the issue's labels. It will add any missing labels
and remove any that don't belong, and it will remove the `status/need-issue`
label if it was present.
- **What you should do**:
- **Always link your PR to an issue.** This is the most important step. Add a
line like `Resolves #<issue-number>` to your PR description.
- This will ensure your PR is correctly categorized and moves through the
review process smoothly.
### 4. Ongoing triage for issues: `Scheduled Issue Triage`
This is a fallback workflow to ensure that no issue gets missed by the triage
process.
- **Workflow File**: `.github/workflows/gemini-scheduled-issue-triage.yml`
- **When it runs**: Every hour on all open issues.
- **What it does**:
- It actively seeks out issues that either have no labels at all or still have
the `status/need-triage` label.
- It then triggers the same powerful Gemini-based analysis as the initial
triage bot to apply the correct labels.
- **What you should do**:
- You typically don't need to do anything. This workflow is a safety net to
ensure every issue is eventually categorized, even if the initial triage
fails.
### 5. Automatic unassignment of inactive contributors: `Unassign Inactive Issue Assignees`
To keep the list of open `help wanted` issues accessible to all contributors,
this workflow automatically removes **external contributors** who have not
opened a linked pull request within **7 days** of being assigned. Maintainers,
org members, and repo collaborators with write access or above are always exempt
and will never be auto-unassigned.
- **Workflow File**: `.github/workflows/unassign-inactive-assignees.yml`
- **When it runs**: Every day at 09:00 UTC, and can be triggered manually with
an optional `dry_run` mode.
- **What it does**:
1. Finds every open issue labeled `help wanted` that has at least one
assignee.
2. Identifies privileged users (team members, repo collaborators with write+
access, maintainers) and skips them entirely.
3. For each remaining (external) assignee it reads the issue's timeline to
determine:
- The exact date they were assigned (using `assigned` timeline events).
- Whether they have opened a PR that is already linked/cross-referenced to
the issue.
4. Each cross-referenced PR is fetched to verify it is **ready for review**:
open and non-draft, or already merged. Draft PRs do not count.
5. If an assignee has been assigned for **more than 7 days** and no qualifying
PR is found, they are automatically unassigned and a comment is posted
explaining the reason and how to re-claim the issue.
6. Assignees who have a non-draft, open or merged PR linked to the issue are
**never** unassigned by this workflow.
- **What you should do**:
- **Open a real PR, not a draft**: Within 7 days of being assigned, open a PR
that is ready for review and include `Fixes #<issue-number>` in the
description. Draft PRs do not satisfy the requirement and will not prevent
auto-unassignment.
- **Re-assign if unassigned by mistake**: Comment `/assign` on the issue to
assign yourself again.
- **Unassign yourself** if you can no longer work on the issue by commenting
`/unassign`, so other contributors can pick it up right away.
### 6. Automatically label PRs by size: `PR Size Labeler`
To help maintainers estimate review effort and keep the PR history clean, this
workflow automatically tags every pull request with a size label representing
the total volume of line changes.
- **Workflow File**: `.github/workflows/pr-size-labeler.yml`
- **When it runs**: Immediately after a pull request is created, synchronized
(new commits pushed), or reopened. It can also be triggered manually via
`workflow_dispatch` with a PR number.
- **What it does**:
- **Calculates total changes**: Summarizes additions and deletions across all
changed files in a single consolidated API request.
- **Applies standard size labels**:
- `size/XS`: < 10 lines changed
- `size/S`: 10-49 lines changed
- `size/M`: 50-249 lines changed
- `size/L`: 250-999 lines changed
- `size/XL`: >= 1000 lines changed
- **Updates size tag atomically**: Adds the new correct size label and removes
any obsolete size labels in one atomic step.
- **Updates/Posts PR size info comment**: Instead of spamming a new comment on
every commit push, it updates the existing size labeler status comment
inline to keep the PR conversation timeline perfectly neat and clean.
- **What you should do**:
- You do not need to take any actions. The workflow runs automatically and
updates the label and comment seamlessly as you push new updates.
### 7. Release automation
This workflow handles the process of packaging and publishing new versions of
Gemini CLI.
- **Workflow File**: `.github/workflows/release-manual.yml`
- **When it runs**: On a daily schedule for "nightly" releases, and manually for
official patch/minor releases.
- **What it does**:
- Automatically builds the project, bumps the version numbers, and publishes
the packages to npm.
- Creates a corresponding release on GitHub with generated release notes.
- **What you should do**:
- As a contributor, you don't need to do anything for this process. You can be
confident that once your PR is merged into the `main` branch, your changes
will be included in the very next nightly release.
We hope this detailed overview is helpful. If you have any questions about our
automation or processes, don't hesitate to ask!
# [Gemini CLI documentation](http://geminicli.com/docs.md)
Gemini CLI brings the power of Gemini models directly into your terminal. Use it
to understand code, automate tasks, and build workflows with your local project
context.
## Install
```bash
npm install -g @google/gemini-cli
```
## Get started
Jump in to Gemini CLI.
- **[Quickstart](/docs/get-started):** Your first session with Gemini CLI.
- **[Installation](/docs/get-started/installation):** How to install Gemini CLI
on your system.
- **[Authentication](/docs/get-started/authentication):** Setup instructions for
personal and enterprise accounts.
- **[CLI cheatsheet](/docs/cli/cli-reference):** A quick reference for common
commands and options.
- **[Gemini 3 on Gemini CLI](/docs/get-started/gemini-3):** Learn about Gemini 3
support in Gemini CLI.
## Use Gemini CLI
User-focused guides and tutorials for daily development workflows.
- **[File management](/docs/cli/tutorials/file-management):** How to work with
local files and directories.
- **[Get started with Agent skills](/docs/cli/tutorials/skills-getting-started):**
Getting started with specialized expertise.
- **[Manage context and memory](/docs/cli/tutorials/memory-management):**
Managing persistent instructions and facts.
- **[Execute shell commands](/docs/cli/tutorials/shell-commands):** Executing
system commands safely.
- **[Manage sessions and history](/docs/cli/tutorials/session-management):**
Resuming, managing, and rewinding conversations.
- **[Plan tasks with todos](/docs/cli/tutorials/task-planning):** Using todos for
complex workflows.
- **[Web search and fetch](/docs/cli/tutorials/web-tools):** Searching and
fetching content from the web.
- **[Set up an MCP server](/docs/cli/tutorials/mcp-setup):** Set up an MCP
server.
- **[Automate tasks](/docs/cli/tutorials/automation):** Automate tasks.
## Features
Technical documentation for each capability of Gemini CLI.
- **[Extensions](/docs/extensions):** Extend Gemini CLI with new tools and
capabilities.
- **[Agent Skills](/docs/cli/skills):** Use specialized agents for specific
tasks.
- **[Checkpointing](/docs/cli/checkpointing):** Automatic session snapshots.
- **[Headless mode](/docs/cli/headless):** Programmatic and scripting interface.
- **[Hooks](/docs/hooks):** Customize Gemini CLI behavior with scripts.
- **[IDE integration](/docs/ide-integration):** Integrate Gemini CLI with
your favorite IDE.
- **[MCP servers](/docs/tools/mcp-server):** Connect to and use remote agents.
- **[Model routing](/docs/cli/model-routing):** Automatic fallback resilience.
- **[Model selection](/docs/cli/model):** Choose the best model for your needs.
- **[Plan mode 🔬](/docs/cli/plan-mode):** Use a safe, read-only mode for
planning complex changes.
- **[Subagents 🔬](/docs/core/subagents):** Using specialized agents for specific
tasks.
- **[Remote subagents 🔬](/docs/core/remote-agents):** Connecting to and using
remote agents.
- **[Rewind](/docs/cli/rewind):** Rewind and replay sessions.
- **[Sandboxing](/docs/cli/sandbox):** Isolate tool execution.
- **[Settings](/docs/cli/settings):** Full configuration reference.
- **[Telemetry](/docs/cli/telemetry):** Usage and performance metric details.
- **[Token caching](/docs/cli/token-caching):** Performance optimization.
## Configuration
Settings and customization options for Gemini CLI.
- **[Custom commands](/docs/cli/custom-commands):** Personalized shortcuts.
- **[Enterprise configuration](/docs/cli/enterprise):** Professional environment
controls.
- **[Ignore files (.geminiignore)](/docs/cli/gemini-ignore):** Exclusion pattern
reference.
- **[Model configuration](/docs/cli/generation-settings):** Fine-tune generation
parameters like temperature and thinking budget.
- **[Project context (GEMINI.md)](/docs/cli/gemini-md):** Technical hierarchy of
context files.
- **[System prompt override](/docs/cli/system-prompt):** Instruction replacement
logic.
- **[Themes](/docs/cli/themes):** UI personalization technical guide.
- **[Trusted folders](/docs/cli/trusted-folders):** Security permission logic.
## Reference
Deep technical documentation and API specifications.
- **[Command reference](/docs/reference/commands):** Detailed slash command
guide.
- **[Configuration reference](/docs/reference/configuration):** Settings and
environment variables.
- **[Keyboard shortcuts](/docs/reference/keyboard-shortcuts):** Productivity
tips.
- **[Memory import processor](/docs/reference/memport):** How Gemini CLI
processes memory from various sources.
- **[Policy engine](/docs/reference/policy-engine):** Fine-grained execution
control.
- **[Tools reference](/docs/reference/tools):** Information on how tools are
defined, registered, and used.
## Resources
Support, release history, and legal information.
- **[FAQ](/docs/resources/faq):** Answers to frequently asked questions.
- **[Quota and pricing](/docs/resources/quota-and-pricing):** Limits and billing
details.
- **[Terms and privacy](/docs/resources/tos-privacy):** Official notices and
terms.
- **[Troubleshooting](/docs/resources/troubleshooting):** Common issues and
solutions.
- **[Uninstall](/docs/resources/uninstall):** How to uninstall Gemini CLI.
## Development
- **[Contribution guide](/docs/contributing):** How to contribute to Gemini CLI.
- **[Integration testing](/docs/integration-tests):** Running integration tests.
- **[Issue and PR automation](/docs/issue-and-pr-automation):** Automation for
issues and pull requests.
- **[Local development](/docs/local-development):** Setting up a local
development environment.
- **[NPM package structure](/docs/npm):** The structure of the NPM packages.
## Releases
- **[Release notes](/docs/changelogs):** Release notes for all versions.
- **[Stable release](/docs/changelogs/latest):** The latest stable release.
- **[Preview release](/docs/changelogs/preview):** The latest preview release.
# [Release confidence strategy](http://geminicli.com/docs/release-confidence.md)
This document outlines the strategy for gaining confidence in every release of
Gemini CLI. It serves as a checklist and quality gate for release manager to
ensure we are shipping a high-quality product.
## The goal
To answer the question, "Is this release _truly_ ready for our users?" with a
high degree of confidence, based on a holistic evaluation of automated signals,
manual verification, and data.
## Level 1: Automated gates (must pass)
These are the baseline requirements. If any of these fail, the release is a
no-go.
### 1. CI/CD health
All workflows in `.github/workflows/ci.yml` must pass on the `main` branch (for
nightly) or the release branch (for preview/stable).
- **Platforms:** Tests must pass on **Linux and macOS**.
- **Checks:**
- **Linting:** No linting errors (ESLint, Prettier, etc.).
- **Typechecking:** No TypeScript errors.
- **Unit Tests:** All unit tests in `packages/core` and `packages/cli` must
pass.
- **Build:** The project must build and bundle successfully.
### 2. End-to-end (E2E) tests
All workflows in `.github/workflows/chained_e2e.yml` must pass.
- **Platforms:** **Linux, macOS and Windows**.
- **Sandboxing:** Tests must pass with both `sandbox:none` and `sandbox:docker`
on Linux.
### 3. Post-deployment smoke tests
After a release is published to npm, the `smoke-test.yml` workflow runs. This
must pass to confirm the package is installable and the binary is executable.
- **Command:** `npx -y @google/gemini-cli@<tag> --version` must return the
correct version without error.
- **Platform:** Currently runs on `ubuntu-latest`.
## Level 2: Manual verification and dogfooding
Automated tests cannot catch everything, especially UX issues.
### 1. Dogfooding via `preview` tag
The weekly release cadence promotes code from `main` -> `nightly` -> `preview`
-> `stable`.
- **Requirement:** The `preview` release must be used by maintainers for at
least **one week** before being promoted to `stable`.
- **Action:** Maintainers should install the preview version locally:
```bash
npm install -g @google/gemini-cli@preview
```
- **Goal:** To catch regressions and UX issues in day-to-day usage before they
reach the broad user base.
### 2. Critical user journey (CUJ) checklist
Before promoting a `preview` release to `stable`, a release manager must
manually run through this checklist.
- **Setup:**
- [ ] Uninstall any existing global version:
`npm uninstall -g @google/gemini-cli`
- [ ] Clear npx cache (optional but recommended): `npm cache clean --force`
- [ ] Install the preview version: `npm install -g @google/gemini-cli@preview`
- [ ] Verify version: `gemini --version`
- **Authentication:**
- [ ] In interactive mode run `/auth` and verify all sign in flows work:
- [ ] Sign in with Google
- [ ] API Key
- [ ] Vertex AI
- **Basic prompting:**
- [ ] Run `gemini "Tell me a joke"` and verify a sensible response.
- [ ] Run in interactive mode: `gemini`. Ask a follow-up question to test
context.
- **Piped input:**
- [ ] Run `echo "Summarize this" | gemini` and verify it processes stdin.
- **Context management:**
- [ ] In interactive mode, use `@file` to add a local file to context. Ask a
question about it.
- **Settings:**
- [ ] In interactive mode run `/settings` and make modifications
- [ ] Validate that setting is changed
- **Function calling:**
- [ ] In interactive mode, ask gemini to "create a file named hello.md with
the content 'hello world'" and verify the file is created correctly.
If any of these CUJs fail, the release is a no-go until a patch is applied to
the `preview` channel.
### 3. Pre-Launch bug bash (tier 1 and 2 launches)
For high-impact releases, an organized bug bash is required to ensure a higher
level of quality and