@google/gemini-cli-core 0.22.0-preview.3 → 0.23.0-preview.0

package/dist/docs/extensions/index.md

@@ -0,0 +1,293 @@
+# Gemini CLI extensions
+
+_This documentation is up-to-date with the v0.4.0 release._
+
+Gemini CLI extensions package prompts, MCP servers, and custom commands into a
+familiar and user-friendly format. With extensions, you can expand the
+capabilities of Gemini CLI and share those capabilities with others. They are
+designed to be easily installable and shareable.
+
+To see examples of extensions, you can browse a gallery of
+[Gemini CLI extensions](https://geminicli.com/extensions/browse/).
+
+See [getting started docs](getting-started-extensions.md) for a guide on
+creating your first extension.
+
+See [releasing docs](extension-releasing.md) for an advanced guide on setting up
+GitHub releases.
+
+## Extension management
+
+We offer a suite of extension management tools using `gemini extensions`
+commands.
+
+Note that these commands are not supported from within the CLI, although you can
+list installed extensions using the `/extensions list` subcommand.
+
+Note that all of these commands will only be reflected in active CLI sessions on
+restart.
+
+### Installing an extension
+
+You can install an extension using `gemini extensions install` with either a
+GitHub URL or a local path.
+
+Note that we create a copy of the installed extension, so you will need to run
+`gemini extensions update` to pull in changes from both locally-defined
+extensions and those on GitHub.
+
+NOTE: If you are installing an extension from GitHub, you'll need to have `git`
+installed on your machine. See
+[git installation instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+for help.
+
+```
+gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent]
+```
+
+- `<source>`: The github URL or local path of the extension to install.
+- `--ref`: The git ref to install from.
+- `--auto-update`: Enable auto-update for this extension.
+- `--pre-release`: Enable pre-release versions for this extension.
+- `--consent`: Acknowledge the security risks of installing an extension and
+  skip the confirmation prompt.
+
+### Uninstalling an extension
+
+To uninstall one or more extensions, run
+`gemini extensions uninstall <name...>`:
+
+```
+gemini extensions uninstall gemini-cli-security gemini-cli-another-extension
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an
+extension entirely or for specific workspace.
+
+```
+gemini extensions disable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to disable.
+- `--scope`: The scope to disable the extension in (`user` or `workspace`).
+
+### Enabling an extension
+
+You can enable extensions using `gemini extensions enable <name>`. You can also
+enable an extension for a specific workspace using
+`gemini extensions enable <name> --scope=workspace` from within that workspace.
+
+```
+gemini extensions enable <name> [--scope <scope>]
+```
+
+- `<name>`: The name of the extension to enable.
+- `--scope`: The scope to enable the extension in (`user` or `workspace`).
+
+### Updating an extension
+
+For extensions installed from a local path or a git repository, you can
+explicitly update to the latest version (as reflected in the
+`gemini-extension.json` `version` field) with `gemini extensions update <name>`.
+
+You can update all extensions with:
+
+```
+gemini extensions update --all
+```
+
+### Create a boilerplate extension
+
+We offer several example extensions `context`, `custom-commands`,
+`exclude-tools` and `mcp-server`. You can view these examples
+[here](https://github.com/google-gemini/gemini-cli/tree/main/packages/cli/src/commands/extensions/examples).
+
+To copy one of these examples into a development directory using the type of
+your choosing, run:
+
+```
+gemini extensions new <path> [template]
+```
+
+- `<path>`: The path to create the extension in.
+- `[template]`: The boilerplate template to use.
+
+### Link a local extension
+
+The `gemini extensions link` command will create a symbolic link from the
+extension installation directory to the development path.
+
+This is useful so you don't have to run `gemini extensions update` every time
+you make changes you'd like to test.
+
+```
+gemini extensions link <path>
+```
+
+- `<path>`: The path of the extension to link.
+
+## How it works
+
+On startup, Gemini CLI looks for extensions in `<home>/.gemini/extensions`
+
+Extensions exist as a directory that contains a `gemini-extension.json` file.
+For example:
+
+`<home>/.gemini/extensions/my-extension/gemini-extension.json`
+
+### `gemini-extension.json`
+
+The `gemini-extension.json` file contains the configuration for the extension.
+The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the
+  extension and for conflict resolution when extension commands have the same
+  name as user or project commands. The name should be lowercase or numbers and
+  use dashes instead of underscores or spaces. This is how users will refer to
+  your extension in the CLI. Note that we expect this name to match the
+  extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to settings. The key is the name of the
+  server, and the value is the server configuration. These servers will be
+  loaded on startup just like MCP servers settingsd in a
+  [`settings.json` file](../get-started/configuration.md). If both an extension
+  and a `settings.json` file settings an MCP server with the same name, the
+  server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for
+    `trust`.
+- `contextFileName`: The name of the file that contains the context for the
+  extension. This will be used to load the context from the extension directory.
+  If this property is not used but a `GEMINI.md` file is present in your
+  extension directory, then that file will be loaded.
+- `excludeTools`: An array of tool names to exclude from the model. You can also
+  specify command-specific restrictions for tools that support it, like the
+  `run_shell_command` tool. For example,
+  `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf`
+  command. Note that this differs from the MCP server `excludeTools`
+  functionality, which can be listed in the MCP server config.
+
+When Gemini CLI starts, it loads all the extensions and merges their
+configurations. If there are any conflicts, the workspace configuration takes
+precedence.
+
+### Settings
+
+_Note: This is an experimental feature. We do not yet recommend extension
+authors introduce settings as part of their core flows._
+
+Extensions can define settings that the user will be prompted to provide upon
+installation. This is useful for things like API keys, URLs, or other
+configuration that the extension needs to function.
+
+To define settings, add a `settings` array to your `gemini-extension.json` file.
+Each object in the array should have the following properties:
+
+- `name`: A user-friendly name for the setting.
+- `description`: A description of the setting and what it's used for.
+- `envVar`: The name of the environment variable that the setting will be stored
+  as.
+- `sensitive`: Optional boolean. If true, obfuscates the input the user provides
+  and stores the secret in keychain storage. **Example**
+
+```json
+{
+  "name": "my-api-extension",
+  "version": "1.0.0",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service.",
+      "envVar": "MY_API_KEY"
+    }
+  ]
+}
+```
+
+When a user installs this extension, they will be prompted to enter their API
+key. The value will be saved to a `.env` file in the extension's directory
+(e.g., `<home>/.gemini/extensions/my-api-extension/.env`).
+
+You can view a list of an extension's settings by running:
+
+```
+gemini extensions settings list <extension name>
+```
+
+and you can update a given setting using:
+
+```
+gemini extensions settings set <extension name> <setting name> [--scope <scope>]
+```
+
+- `--scope`: The scope to set the setting in (`user` or `workspace`). This is
+  optional and will default to `user`.
+
+### Custom commands
+
+Extensions can provide [custom commands](../cli/custom-commands.md) by placing
+TOML files in a `commands/` subdirectory within the extension directory. These
+commands follow the same format as user and project custom commands and use
+standard naming conventions.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.gemini/extensions/gcp/
+├── gemini-extension.json
+└── commands/
+    ├── deploy.toml
+    └── gcs/
+        └── sync.toml
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user
+or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix
+   (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]`
+  tag)
+
+## Variables
+
+Gemini CLI extensions allow variable substitution in `gemini-extension.json`.
+This can be useful if e.g., you need the current directory to run an MCP server
+using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                     |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.gemini/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                              |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                            |

package/dist/docs/faq.md

@@ -0,0 +1,154 @@
+# Frequently asked questions (FAQ)
+
+This page provides answers to common questions and solutions to frequent
+problems encountered while using Gemini CLI.
+
+## General issues
+
+### Why am I getting an `API error: 429 - Resource exhausted`?
+
+This error indicates that you have exceeded your API request limit. The Gemini
+API has rate limits to prevent abuse and ensure fair usage.
+
+To resolve this, you can:
+
+- **Check your usage:** Review your API usage in the Google AI Studio or your
+  Google Cloud project dashboard.
+- **Optimize your prompts:** If you are making many requests in a short period,
+  try to batch your prompts or introduce delays between requests.
+- **Request a quota increase:** If you consistently need a higher limit, you can
+  request a quota increase from Google.
+
+### Why am I getting an `ERR_REQUIRE_ESM` error when running `npm run start`?
+
+This error typically occurs in Node.js projects when there is a mismatch between
+CommonJS and ES Modules.
+
+This is often due to a misconfiguration in your `package.json` or
+`tsconfig.json`. Ensure that:
+
+1.  Your `package.json` has `"type": "module"`.
+2.  Your `tsconfig.json` has `"module": "NodeNext"` or a compatible setting in
+    the `compilerOptions`.
+
+If the problem persists, try deleting your `node_modules` directory and
+`package-lock.json` file, and then run `npm install` again.
+
+### Why don't I see cached token counts in my stats output?
+
+Cached token information is only displayed when cached tokens are being used.
+This feature is available for API key users (Gemini API key or Google Cloud
+Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts
+like Google Gmail or Google Workspace, respectively). This is because the Gemini
+Code Assist API does not support cached content creation. You can still view
+your total token usage using the `/stats` command in Gemini CLI.
+
+## Installation and updates
+
+### How do I update Gemini CLI to the latest version?
+
+If you installed it globally via `npm`, update it using the command
+`npm install -g @google/gemini-cli@latest`. If you compiled it from source, pull
+the latest changes from the repository, and then rebuild using the command
+`npm run build`.
+
+## Platform-specific issues
+
+### Why does the CLI crash on Windows when I run a command like `chmod +x`?
+
+Commands like `chmod` are specific to Unix-like operating systems (Linux,
+macOS). They are not available on Windows by default.
+
+To resolve this, you can:
+
+- **Use Windows-equivalent commands:** Instead of `chmod`, you can use `icacls`
+  to modify file permissions on Windows.
+- **Use a compatibility layer:** Tools like Git Bash or Windows Subsystem for
+  Linux (WSL) provide a Unix-like environment on Windows where these commands
+  will work.
+
+## Configuration
+
+### How do I configure my `GOOGLE_CLOUD_PROJECT`?
+
+You can configure your Google Cloud Project ID using an environment variable.
+
+Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell:
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+To make this setting permanent, add this line to your shell's startup file
+(e.g., `~/.bashrc`, `~/.zshrc`).
+
+### What is the best way to store my API keys securely?
+
+Exposing API keys in scripts or checking them into source control is a security
+risk.
+
+To store your API keys securely, you can:
+
+- **Use a `.env` file:** Create a `.env` file in your project's `.gemini`
+  directory (`.gemini/.env`) and store your keys there. Gemini CLI will
+  automatically load these variables.
+- **Use your system's keyring:** For the most secure storage, use your operating
+  system's secret management tool (like macOS Keychain, Windows Credential
+  Manager, or a secret manager on Linux). You can then have your scripts or
+  environment load the key from the secure storage at runtime.
+
+### Where are the Gemini CLI configuration and settings files stored?
+
+The Gemini CLI configuration is stored in two `settings.json` files:
+
+1.  In your home directory: `~/.gemini/settings.json`.
+2.  In your project's root directory: `./.gemini/settings.json`.
+
+Refer to [Gemini CLI Configuration](./get-started/configuration.md) for more
+details.
+
+## Google AI Pro/Ultra and subscription FAQs
+
+### Where can I learn more about my Google AI Pro or Google AI Ultra subscription?
+
+To learn more about your Google AI Pro or Google AI Ultra subscription, visit
+**Manage subscription** in your [subscription settings](https://one.google.com).
+
+### How do I know if I have higher limits for Google AI Pro or Ultra?
+
+If you're subscribed to Google AI Pro or Ultra, you automatically have higher
+limits to Gemini Code Assist and Gemini CLI. These are shared across Gemini CLI
+and agent mode in the IDE. You can confirm you have higher limits by checking if
+you are still subscribed to Google AI Pro or Ultra in your
+[subscription settings](https://one.google.com).
+
+### What is the privacy policy for using Gemini Code Assist or Gemini CLI if I've subscribed to Google AI Pro or Ultra?
+
+To learn more about your privacy policy and terms of service governed by your
+subscription, visit
+[Gemini Code Assist: Terms of Service and Privacy Policies](https://developers.google.com/gemini-code-assist/resources/privacy-notices).
+
+### I've upgraded to Google AI Pro or Ultra but it still says I am hitting quota limits. Is this a bug?
+
+The higher limits in your Google AI Pro or Ultra subscription are for Gemini 2.5
+across both Gemini 2.5 Pro and Flash. They are shared quota across Gemini CLI
+and agent mode in Gemini Code Assist IDE extensions. You can learn more about
+quota limits for Gemini CLI, Gemini Code Assist and agent mode in Gemini Code
+Assist at
+[Quotas and limits](https://developers.google.com/gemini-code-assist/resources/quotas).
+
+### If I upgrade to higher limits for Gemini CLI and Gemini Code Assist by purchasing a Google AI Pro or Ultra subscription, will Gemini start using my data to improve its machine learning models?
+
+Google does not use your data to improve Google's machine learning models if you
+purchase a paid plan. Note: If you decide to remain on the free version of
+Gemini Code Assist, Gemini Code Assist for individuals, you can also opt out of
+using your data to improve Google's machine learning models. See the
+[Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals)
+for more information.
+
+## Not seeing your question?
+
+Search the
+[Gemini CLI Q&A discussions on GitHub](https://github.com/google-gemini/gemini-cli/discussions/categories/q-a)
+or
+[start a new discussion on GitHub](https://github.com/google-gemini/gemini-cli/discussions/new?category=q-a)