diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84e6bc483e..4588619867 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,6 @@ # How to contribute -We would love to accept your patches and contributions to this project. This -document includes: +Contributions and patches to this project are welcome. This document includes: - **[Before you begin](#before-you-begin):** Essential steps to take before becoming a Gemini CLI contributor. @@ -12,7 +11,7 @@ document includes: - **[Documentation contribution process](#documentation-contribution-process):** How to contribute documentation to Gemini CLI. -We're looking forward to seeing your contributions! +Your contributions are appreciated! ## Before you begin @@ -42,13 +41,13 @@ This project follows The process for contributing code is as follows: 1. **Find an issue** that you want to work on. If an issue is tagged as - `🔒Maintainers only`, this means it is reserved for project maintainers. We - will not accept pull requests related to these issues. In the near future, - we will explicitly mark issues looking for contributions using the + `🔒Maintainers only`, this means it is reserved for project maintainers. + Pull requests related to these issues are not accepted. In the near future, + issues looking for contributions will be explicitly marked using the `help-wanted` label. If you believe an issue is a good candidate for - community contribution, please leave a comment on the issue. A maintainer - will review it and apply the `help-wanted` label if appropriate. Only - maintainers should attempt to add the `help-wanted` label to an issue. + community contribution, leave a comment on the issue. A maintainer will + review it and apply the `help-wanted` label if appropriate. Only maintainers + add the `help-wanted` label to an issue. 2. **Fork the repository** and create a new branch. 3. **Make your changes** in the `packages/` directory. 4. **Ensure all checks pass** by running `npm run preflight`. @@ -56,22 +55,21 @@ The process for contributing code is as follows: ### Code reviews -All submissions, including submissions by project members, require review. We -use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests) -for this purpose. +All submissions, including submissions by project members, require review. +Gemini CLI uses +[GitHub pull requests](https://docs.github.com/articles/about-pull-requests) for +this purpose. -To assist with the review process, we provide an automated review tool that -helps detect common anti-patterns, testing issues, and other best practices that -are easy to miss. +To assist with the review process, an automated review tool helps detect common +anti-patterns, testing issues, and other best practices that are easy to miss. #### Using the automated review tool You can run the review tool in two ways: -1. **Using the helper script (Recommended):** We provide a script that - automatically handles checking out the PR into a separate worktree, - installing dependencies, building the project, and launching the review - tool. +1. **Using the helper script (Recommended):** A script automatically handles + checking out the PR into a separate worktree, installing dependencies, + building the project, and launching the review tool. ```bash ./scripts/review.sh [model] @@ -97,7 +95,7 @@ You can run the review tool in two ways: /review-frontend ``` -Replace `` with your pull request number. Reviewers should use this +Replace `` with your pull request number. Reviewers must use this tool to augment, not replace, their manual review process. ### Self-assigning and unassigning issues @@ -105,39 +103,39 @@ tool to augment, not replace, their manual review process. To assign an issue to yourself, simply add a comment with the text `/assign`. To unassign yourself from an issue, add a comment with the text `/unassign`. -The comment must contain only that text and nothing else. These commands will -assign or unassign the issue as requested, provided the conditions are met -(e.g., an issue must be unassigned to be assigned). +The comment must contain only that text and nothing else. These commands assign +or unassign the issue as requested, provided the conditions are met (for +example, an issue must be unassigned to be assigned). -Please note that you can have a maximum of 3 issues assigned to you at any given -time and that only +Note that you can have a maximum of 3 issues assigned to you at any given time +and that only [issues labeled "help wanted"](https://github.com/google-gemini/gemini-cli/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) may be self-assigned. ### Pull request guidelines -To help us review and merge your PRs quickly, please follow these guidelines. -PRs that do not meet these standards may be closed. +To ensure quick review and merging of your PRs, follow these guidelines. PRs +that do not meet these standards may be closed. #### 1. Link to an existing issue -All PRs should be linked to an existing issue in our tracker. This ensures that +All PRs must be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written. -- **For bug fixes:** The PR should be linked to the bug report issue. -- **For features:** The PR should be linked to the feature request or proposal +- **For bug fixes:** The PR must be linked to the bug report issue. +- **For features:** The PR must be linked to the feature request or proposal issue that has been approved by a maintainer. -If an issue for your change doesn't exist, we will automatically close your PR -along with a comment reminding you to associate the PR with an issue. The ideal -workflow starts with an issue that has been reviewed and approved by a -maintainer. Please **open the issue first** and wait for feedback before you -start coding. +If an issue for your change doesn't exist, Gemini CLI automatically closes your +PR along with a comment reminding you to associate the PR with an issue. The +ideal workflow starts with an issue that has been reviewed and approved by a +maintainer. **Open the issue first** and wait for feedback before you start +coding. #### 2. Keep it small and focused -We favor small, atomic PRs that address a single issue or add a single, +Gemini CLI favors small, atomic PRs that address a single issue or add a single, self-contained feature. - **Do:** Create a PR that fixes one specific bug or adds one specific feature. @@ -149,9 +147,9 @@ can be reviewed and merged independently. #### 3. Use draft PRs for work in progress -If you'd like to get early feedback on your work, please use GitHub's **Draft -Pull Request** feature. This signals to the maintainers that the PR is not yet -ready for a formal review but is open for discussion and initial feedback. +To get early feedback on your work, use GitHub's **Draft Pull Request** feature. +This signals to the maintainers that the PR is not yet ready for a formal review +but is open for discussion and initial feedback. #### 4. Ensure all checks pass @@ -170,7 +168,7 @@ See more about writing documentation: #### 6. Write clear commit messages and a good PR description -Your PR should have a clear, descriptive title and a detailed description of the +Your PR must have a clear, descriptive title and a detailed description of the changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for your commit messages. @@ -178,21 +176,19 @@ standard for your commit messages. - **Bad PR title:** `Made some changes` In the PR description, explain the "why" behind your changes and link to the -relevant issue (e.g., `Fixes #123`). +relevant issue (for example, `Fixes #123`). ### Forking -If you are forking the repository you will be able to run the Build, Test and -Integration test workflows. However in order to make the integration tests run -you'll need to add a +If you fork the repository, you can run the Build, Test and Integration test +workflows. To run the integration tests, add a [GitHub Repository Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) -with a value of `GEMINI_API_KEY` and set that to a valid API key that you have -available. Your key and secret are private to your repo; no one without access -can see your key and you cannot see any secrets related to this repo. +with a value of `GEMINI_API_KEY` and set that to a valid API key. Your key and +secret are private to your repo; no one without access can see your key and you +cannot see any secrets related to this repo. -Additionally you will need to click on the `Actions` tab and enable workflows -for your repository, you'll find it's the large blue button in the center of the -screen. +Additionally, click on the `Actions` tab and enable workflows for your +repository. It is the large blue button in the center of the screen. ### Development setup and workflow @@ -204,9 +200,9 @@ development setup of this project. **Prerequisites:** 1. **Node.js**: - - **Development:** Please use Node.js `~20.19.0`. This specific version is - required due to an upstream development dependency issue. You can use a - tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. + - **Development:** Use Node.js `~20.19.0`. This specific version is required + due to an upstream development dependency issue. Use a tool like + [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. - **Production:** For running the CLI in a production environment, any version of Node.js `>=20` is acceptable. 2. **Git** @@ -261,10 +257,10 @@ command from the root directory: npm start ``` -If you'd like to run the source build outside of the gemini-cli folder, you can -utilize `npm link path/to/gemini-cli/packages/cli` (see: +To run the source build outside of the gemini-cli folder, use +`npm link path/to/gemini-cli/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) or -`alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini` +`alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini`. ### Running tests @@ -284,8 +280,8 @@ comprehensive check, it is recommended to run `npm run preflight`. #### Integration tests -The integration tests are designed to validate the end-to-end functionality of -the Gemini CLI. They are not run as part of the default `npm run test` command. +The integration tests validate the end-to-end functionality of the Gemini CLI. +They are not run as part of the default `npm run test` command. To run the integration tests, use the following command: @@ -293,8 +289,7 @@ To run the integration tests, use the following command: npm run test:e2e ``` -For more detailed information on the integration testing framework, please see -the +For more detailed information on the integration testing framework, see the [Integration Tests documentation](https://geminicli.com/docs/integration-tests). ### Linting and preflight checks @@ -305,8 +300,8 @@ To ensure code quality and formatting consistency, run the preflight check: npm run preflight ``` -This command will run ESLint, Prettier, all tests, and other checks as defined -in the project's `package.json`. +This command runs ESLint, Prettier, all tests, and other checks as defined in +the project's `package.json`. _ProTip_ @@ -346,8 +341,8 @@ npm run lint ### Coding conventions -- Please adhere to the coding style, patterns, and conventions used throughout - the existing codebase. +- Adhere to the coding style, patterns, and conventions used throughout the + existing codebase. - Consult [GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to @@ -470,8 +465,8 @@ sandbox. ### Manual publish -We publish an artifact for each commit to our internal registry. But if you need -to manually cut a local build, then run the following commands: +Gemini CLI publishes an artifact for each commit to an internal registry. To +manually cut a local build, use these commands: ``` npm run clean @@ -483,8 +478,8 @@ npm publish --workspaces ## Documentation contribution process -Our documentation must be kept up-to-date with our code contributions. We want -our documentation to be clear, concise, and helpful to our users. We value: +Gemini CLI documentation must be kept up-to-date with code contributions. +Documentation should be clear, concise, and helpful to users. Gemini CLI values: - **Clarity:** Use simple and direct language. Avoid jargon where possible. - **Accuracy:** Ensure all information is correct and up-to-date. @@ -494,13 +489,12 @@ our documentation to be clear, concise, and helpful to our users. We value: ### Getting started -The process for contributing to the documentation is similar to contributing -code. +Documentation contributions follow a process similar to code contributions. 1. **Fork the repository** and create a new branch. 2. **Make your changes** in the `/docs` directory. 3. **Preview your changes locally** in Markdown rendering. -4. **Lint and format your changes.** Our preflight check includes linting and +4. **Lint and format your changes.** The preflight check includes linting and formatting for documentation files. ```bash npm run preflight @@ -519,9 +513,9 @@ as the table of contents. When adding new documentation: ### Style guide -We follow the +Gemini CLI follows the [Google Developer Documentation Style Guide](https://developers.google.com/style). -Please refer to it for guidance on writing style, tone, and formatting. +Refer to it for guidance on writing style, tone, and formatting. #### Key style points @@ -534,8 +528,8 @@ Please refer to it for guidance on writing style, tone, and formatting. ### Linting and formatting -We use `prettier` to enforce a consistent style across our documentation. The -`npm run preflight` command will check for any linting issues. +Gemini CLI uses `prettier` to enforce a consistent style across our +documentation. The `npm run preflight` command checks for any linting issues. You can also run the linter and formatter separately: @@ -543,12 +537,10 @@ You can also run the linter and formatter separately: - `npm run format` - Auto-format markdown files - `npm run lint:fix` - Auto-fix linting issues where possible -Please make sure your contributions are free of linting errors before submitting -a pull request. +Ensure your contributions are free of linting errors before submitting a pull +request. -### Before you submit - -Before submitting your documentation pull request, please: +### Before submitting 1. Run `npm run preflight` to ensure all checks pass. 2. Review your changes for clarity and accuracy. @@ -562,10 +554,10 @@ Before submitting your documentation pull request, please: If you have questions about contributing documentation: -- Check our [FAQ](https://geminicli.com/docs/resources/faq). +- Check the [FAQ](https://geminicli.com/docs/resources/faq). - Review existing documentation for examples. - Open [an issue](https://github.com/google-gemini/gemini-cli/issues) to discuss your proposed changes. - Reach out to the maintainers. -We appreciate your contributions to making Gemini CLI documentation better! +Gemini CLI appreciates your contributions to making its documentation better! diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md index e8217e226e..d5633e74fe 100644 --- a/docs/cli/cli-reference.md +++ b/docs/cli/cli-reference.md @@ -5,6 +5,9 @@ and parameters. ## CLI commands +Gemini CLI provides a range of commands for starting sessions, updating the +application, and managing extensions and MCP servers. + | Command | Description | Example | | ---------------------------------- | ---------------------------------- | ------------------------------------------------------------ | | `gemini` | Start interactive REPL | `gemini` | @@ -17,10 +20,14 @@ and parameters. | `gemini -r "" "query"` | Resume session by ID | `gemini -r "abc123" "Finish this PR"` | | `gemini update` | Update to latest version | `gemini update` | | `gemini extensions` | Manage extensions | See [Extensions Management](#extensions-management) | +| `gemini hooks` | Manage hooks | See [Hooks Management](#hooks-management) | | `gemini mcp` | Configure MCP servers | See [MCP Server Management](#mcp-server-management) | +| `gemini skills` | Manage agent skills | See [Skills Management](#skills-management) | ### Positional arguments +Use positional arguments to provide a prompt directly from the command line. + | Argument | Type | Description | | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | | `query` | string (variadic) | Positional prompt. Defaults to interactive mode in a TTY. Use `-p/--prompt` for non-interactive execution. | @@ -42,6 +49,8 @@ These commands are available within the interactive REPL. ## CLI Options +Configure the behavior of Gemini CLI using these command-line options. + | Option | Alias | Type | Default | Description | | -------------------------------- | ----- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--debug` | `-d` | boolean | `false` | Run in debug mode with verbose logging | @@ -85,6 +94,8 @@ These are convenient shortcuts that map to specific models: ## Extensions management +Manage your Gemini CLI extensions with these commands. + | Command | Description | Example | | -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | | `gemini extensions install ` | Install extension from Git URL or local path | `gemini extensions install https://github.com/user/my-extension` | @@ -99,11 +110,24 @@ These are convenient shortcuts that map to specific models: | `gemini extensions link ` | Link local extension for development | `gemini extensions link /path/to/extension` | | `gemini extensions new ` | Create new extension from template | `gemini extensions new ./my-extension` | | `gemini extensions validate ` | Validate extension structure | `gemini extensions validate ./my-extension` | +| `gemini extensions configure ` | Configure an extension | `gemini extensions configure my-extension` | See [Extensions Documentation](../extensions/index.md) for more details. +## Hooks management + +Manage your Gemini CLI hooks with these commands. + +| Command | Description | Example | +| ---------------------- | -------------------- | ---------------------- | +| `gemini hooks migrate` | Migrate legacy hooks | `gemini hooks migrate` | + +See [Hooks Documentation](../hooks/index.md) for more details. + ## MCP server management +Manage your Model Context Protocol (MCP) servers with these commands. + | Command | Description | Example | | ------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | | `gemini mcp add ` | Add stdio-based MCP server | `gemini mcp add github npx -y @modelcontextprotocol/server-github` | @@ -113,11 +137,15 @@ See [Extensions Documentation](../extensions/index.md) for more details. | `gemini mcp add --include-tools tool1,tool2` | Add with specific tools | `gemini mcp add github npx -y @modelcontextprotocol/server-github --include-tools list_repos,get_pr` | | `gemini mcp remove ` | Remove an MCP server | `gemini mcp remove github` | | `gemini mcp list` | List all configured MCP servers | `gemini mcp list` | +| `gemini mcp enable ` | Enable an MCP server | `gemini mcp enable github` | +| `gemini mcp disable ` | Disable an MCP server | `gemini mcp disable github` | See [MCP Server Integration](../tools/mcp-server.md) for more details. ## Skills management +Manage your agent skills with these commands. + | Command | Description | Example | | -------------------------------- | ------------------------------------- | ------------------------------------------------- | | `gemini skills list` | List all discovered agent skills | `gemini skills list` | diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index a5a6aa1eb2..baa209e926 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -2545,29 +2545,29 @@ image separately and reference that image in your sandbox configuration. ## Usage statistics -To help us improve Gemini CLI, we collect anonymized usage statistics. This data -helps us understand how the CLI is used, identify common issues, and prioritize -new features. +To improve Gemini CLI, Gemini CLI collects anonymized usage statistics. This +data helps identify common issues and prioritize new features. -**What we collect:** +**Collected data:** -- **Tool calls:** We log the names of the tools that are called, whether they - succeed or fail, and how long they take to execute. We do not collect the - arguments passed to the tools or any data returned by them. -- **API requests:** We log the Gemini model used for each request, the duration - of the request, and whether it was successful. We do not collect the content - of the prompts or responses. -- **Session information:** We collect information about the configuration of the - CLI, such as the enabled tools and the approval mode. +- **Tool calls:** Gemini CLI logs the names of the tools that are called, + whether they succeed or fail, and how long they take to execute. Gemini CLI + does not collect the arguments passed to the tools or any data returned by + them. +- **API requests:** Gemini CLI logs the Gemini model used for each request, the + duration of the request, and whether it was successful. Gemini CLI does not + collect the content of the prompts or responses. +- **Session information:** Gemini CLI collects information about the + configuration of the CLI, such as the enabled tools and the approval mode. -**What we DON'T collect:** +**Data NOT collected:** -- **Personally identifiable information (PII):** We do not collect any personal - information, such as your name, email address, or API keys. -- **Prompt and response content:** We do not log the content of your prompts or - the responses from the Gemini model. -- **File content:** We do not log the content of any files that are read or - written by the CLI. +- **Personally identifiable information (PII):** Gemini CLI does not collect + personal information, such as your name, email address, or API keys. +- **Prompt and response content:** Gemini CLI does not log the content of your + prompts or the responses from the Gemini model. +- **File content:** Gemini CLI does not log the content of any files that are + read or written by the CLI. **How to opt out:**