mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-17 17:41:24 -07:00
Update sidebar.json and reference + resource files
This commit is contained in:
g-samroberts
154
docs/resources/faq.md
Normal file
154
docs/resources/faq.md
Normal file
@@ -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)
|
||||
158
docs/resources/quota-and-pricing.md
Normal file
158
docs/resources/quota-and-pricing.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Gemini CLI: Quotas and pricing
|
||||
|
||||
Gemini CLI offers a generous free tier that covers many individual developers'
|
||||
use cases. For enterprise or professional usage, or if you need higher limits,
|
||||
several options are available depending on your authentication account type.
|
||||
|
||||
See [privacy and terms](./tos-privacy.md) for details on the Privacy Policy and
|
||||
Terms of Service.
|
||||
|
||||
> **Note:** Published prices are list price; additional negotiated commercial
|
||||
> discounting may apply.
|
||||
|
||||
This article outlines the specific quotas and pricing applicable to Gemini CLI
|
||||
when using different authentication methods.
|
||||
|
||||
Generally, there are three categories to choose from:
|
||||
|
||||
- Free Usage: Ideal for experimentation and light use.
|
||||
- Paid Tier (fixed price): For individual developers or enterprises who need
|
||||
more generous daily quotas and predictable costs.
|
||||
- Pay-As-You-Go: The most flexible option for professional use, long-running
|
||||
tasks, or when you need full control over your usage.
|
||||
|
||||
## Free usage
|
||||
|
||||
Your journey begins with a generous free tier, perfect for experimentation and
|
||||
light use.
|
||||
|
||||
Your free usage limits depend on your authorization type.
|
||||
|
||||
### Log in with Google (Gemini Code Assist for individuals)
|
||||
|
||||
For users who authenticate by using their Google account to access Gemini Code
|
||||
Assist for individuals. This includes:
|
||||
|
||||
- 1000 model requests / user / day
|
||||
- 60 model requests / user / minute
|
||||
- Model requests will be made across the Gemini model family as determined by
|
||||
Gemini CLI.
|
||||
|
||||
Learn more at
|
||||
[Gemini Code Assist for Individuals Limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
|
||||
|
||||
### Log in with Gemini API Key (unpaid)
|
||||
|
||||
If you are using a Gemini API key, you can also benefit from a free tier. This
|
||||
includes:
|
||||
|
||||
- 250 model requests / user / day
|
||||
- 10 model requests / user / minute
|
||||
- Model requests to Flash model only.
|
||||
|
||||
Learn more at
|
||||
[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits).
|
||||
|
||||
### Log in with Vertex AI (Express Mode)
|
||||
|
||||
Vertex AI offers an Express Mode without the need to enable billing. This
|
||||
includes:
|
||||
|
||||
- 90 days before you need to enable billing.
|
||||
- Quotas and models are variable and specific to your account.
|
||||
|
||||
Learn more at
|
||||
[Vertex AI Express Mode Limits](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#quotas).
|
||||
|
||||
## Paid tier: Higher limits for a fixed cost
|
||||
|
||||
If you use up your initial number of requests, you can continue to benefit from
|
||||
Gemini CLI by upgrading to one of the following subscriptions:
|
||||
|
||||
- [Google AI Pro and AI Ultra](https://gemini.google/subscriptions/). This is
|
||||
recommended for individual developers. Quotas and pricing are based on a fixed
|
||||
price subscription.
|
||||
|
||||
For predictable costs, you can log in with Google.
|
||||
|
||||
Learn more at
|
||||
[Gemini Code Assist Quotas and Limits](https://developers.google.com/gemini-code-assist/resources/quotas)
|
||||
|
||||
- [Purchase a Gemini Code Assist Subscription through Google Cloud ](https://cloud.google.com/gemini/docs/codeassist/overview)
|
||||
by signing up in the Google Cloud console. Learn more at
|
||||
[Set up Gemini Code Assist](https://cloud.google.com/gemini/docs/discover/set-up-gemini).
|
||||
|
||||
Quotas and pricing are based on a fixed price subscription with assigned
|
||||
license seats. For predictable costs, you can sign in with Google.
|
||||
|
||||
This includes:
|
||||
- Gemini Code Assist Standard edition:
|
||||
- 1500 model requests / user / day
|
||||
- 120 model requests / user / minute
|
||||
- Gemini Code Assist Enterprise edition:
|
||||
- 2000 model requests / user / day
|
||||
- 120 model requests / user / minute
|
||||
- Model requests will be made across the Gemini model family as determined by
|
||||
Gemini CLI.
|
||||
|
||||
[Learn more about Gemini Code Assist Standard and Enterprise license limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
|
||||
|
||||
## Pay as you go
|
||||
|
||||
If you hit your daily request limits or exhaust your Gemini Pro quota even after
|
||||
upgrading, the most flexible solution is to switch to a pay-as-you-go model,
|
||||
where you pay for the specific amount of processing you use. This is the
|
||||
recommended path for uninterrupted access.
|
||||
|
||||
To do this, log in using a Gemini API key or Vertex AI.
|
||||
|
||||
- Vertex AI (Regular Mode):
|
||||
- Quota: Governed by a dynamic shared quota system or pre-purchased
|
||||
provisioned throughput.
|
||||
- Cost: Based on model and token usage.
|
||||
|
||||
Learn more at
|
||||
[Vertex AI Dynamic Shared Quota](https://cloud.google.com/vertex-ai/generative-ai/docs/resources/dynamic-shared-quota)
|
||||
and [Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing).
|
||||
|
||||
- Gemini API key:
|
||||
- Quota: Varies by pricing tier.
|
||||
- Cost: Varies by pricing tier and model/token usage.
|
||||
|
||||
Learn more at
|
||||
[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits),
|
||||
[Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
|
||||
|
||||
It’s important to highlight that when using an API key, you pay per token/call.
|
||||
This can be more expensive for many small calls with few tokens, but it's the
|
||||
only way to ensure your workflow isn't interrupted by quota limits.
|
||||
|
||||
## Gemini for workspace plans
|
||||
|
||||
These plans currently apply only to the use of Gemini web-based products
|
||||
provided by Google-based experiences (for example, the Gemini web app or the
|
||||
Flow video editor). These plans do not apply to the API usage which powers the
|
||||
Gemini CLI. Supporting these plans is under active consideration for future
|
||||
support.
|
||||
|
||||
## Tips to avoid high costs
|
||||
|
||||
When using a Pay as you Go API key, be mindful of your usage to avoid unexpected
|
||||
costs.
|
||||
|
||||
- Don't blindly accept every suggestion, especially for computationally
|
||||
intensive tasks like refactoring large codebases.
|
||||
- Be intentional with your prompts and commands. You are paying per call, so
|
||||
think about the most efficient way to get the job done.
|
||||
|
||||
## Gemini API vs. Vertex
|
||||
|
||||
- Gemini API (gemini developer api): This is the fastest way to use the Gemini
|
||||
models directly.
|
||||
- Vertex AI: This is the enterprise-grade platform for building, deploying, and
|
||||
managing Gemini models with specific security and control requirements.
|
||||
|
||||
## Understanding your usage
|
||||
|
||||
A summary of model usage is available through the `/stats` command and presented
|
||||
on exit at the end of a session.
|
||||
96
docs/resources/tos-privacy.md
Normal file
96
docs/resources/tos-privacy.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Gemini CLI: License, Terms of Service, and Privacy Notices
|
||||
|
||||
Gemini CLI is an open-source tool that lets you interact with Google's powerful
|
||||
AI services directly from your command-line interface. The Gemini CLI software
|
||||
is licensed under the
|
||||
[Apache 2.0 license](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE).
|
||||
When you use Gemini CLI to access or use Google’s services, the Terms of Service
|
||||
and Privacy Notices applicable to those services apply to such access and use.
|
||||
|
||||
Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
|
||||
Policy.
|
||||
|
||||
**Note:** See [quotas and pricing](/docs/resources/quota-and-pricing.md) for the
|
||||
quota and pricing details that apply to your usage of the Gemini CLI.
|
||||
|
||||
## Supported authentication methods
|
||||
|
||||
Your authentication method refers to the method you use to log into and access
|
||||
Google’s services with Gemini CLI. Supported authentication methods include:
|
||||
|
||||
- Logging in with your Google account to Gemini Code Assist.
|
||||
- Using an API key with Gemini Developer API.
|
||||
- Using an API key with Vertex AI GenAI API.
|
||||
|
||||
The Terms of Service and Privacy Notices applicable to the aforementioned Google
|
||||
services are set forth in the table below.
|
||||
|
||||
If you log in with your Google account and you do not already have a Gemini Code
|
||||
Assist account associated with your Google account, you will be directed to the
|
||||
sign up flow for Gemini Code Assist for individuals. If your Google account is
|
||||
managed by your organization, your administrator may not permit access to Gemini
|
||||
Code Assist for individuals. Please see the
|
||||
[Gemini Code Assist for individuals FAQs](https://developers.google.com/gemini-code-assist/resources/faqs)
|
||||
for further information.
|
||||
|
||||
| Authentication Method | Service(s) | Terms of Service | Privacy Notice |
|
||||
| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
|
||||
| Google Account | Gemini Code Assist services | [Terms of Service](https://developers.google.com/gemini-code-assist/resources/privacy-notices) | [Privacy Notices](https://developers.google.com/gemini-code-assist/resources/privacy-notices) |
|
||||
| Gemini Developer API Key | Gemini API - Unpaid Services | [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services) | [Google Privacy Policy](https://policies.google.com/privacy) |
|
||||
| Gemini Developer API Key | Gemini API - Paid Services | [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services) | [Google Privacy Policy](https://policies.google.com/privacy) |
|
||||
| Vertex AI GenAI API Key | Vertex AI GenAI API | [Google Cloud Platform Terms of Service](https://cloud.google.com/terms/service-terms/) | [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice) |
|
||||
|
||||
## 1. If you have logged in with your Google account to Gemini Code Assist
|
||||
|
||||
For users who use their Google account to access
|
||||
[Gemini Code Assist](https://codeassist.google), these Terms of Service and
|
||||
Privacy Notice documents apply:
|
||||
|
||||
- Gemini Code Assist for individuals:
|
||||
[Google Terms of Service](https://policies.google.com/terms) and
|
||||
[Gemini Code Assist for individuals Privacy Notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals).
|
||||
- Gemini Code Assist with Google AI Pro or Ultra subscription:
|
||||
[Google Terms of Service](https://policies.google.com/terms),
|
||||
[Google One Additional Terms of Service](https://one.google.com/terms-of-service)
|
||||
and [Google Privacy Policy\*](https://policies.google.com/privacy).
|
||||
- Gemini Code Assist Standard and Enterprise editions:
|
||||
[Google Cloud Platform Terms of Service](https://cloud.google.com/terms) and
|
||||
[Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
|
||||
|
||||
_\* If your account is also associated with an active subscription to Gemini
|
||||
Code Assist Standard or Enterprise edition, the terms and privacy policy of
|
||||
Gemini Code Assist Standard or Enterprise edition will apply to all your use of
|
||||
Gemini Code Assist._
|
||||
|
||||
## 2. If you have logged in with a Gemini API key to the Gemini Developer API
|
||||
|
||||
If you are using a Gemini API key for authentication with the
|
||||
[Gemini Developer API](https://ai.google.dev/gemini-api/docs), these Terms of
|
||||
Service and Privacy Notice documents apply:
|
||||
|
||||
- Terms of Service: Your use of the Gemini CLI is governed by the
|
||||
[Gemini API Terms of Service](https://ai.google.dev/gemini-api/terms). These
|
||||
terms may differ depending on whether you are using an unpaid or paid service:
|
||||
- For unpaid services, refer to the
|
||||
[Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services).
|
||||
- For paid services, refer to the
|
||||
[Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services).
|
||||
- Privacy Notice: The collection and use of your data is described in the
|
||||
[Google Privacy Policy](https://policies.google.com/privacy).
|
||||
|
||||
## 3. If you have logged in with a Gemini API key to the Vertex AI GenAI API
|
||||
|
||||
If you are using a Gemini API key for authentication with a
|
||||
[Vertex AI GenAI API](https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest)
|
||||
backend, these Terms of Service and Privacy Notice documents apply:
|
||||
|
||||
- Terms of Service: Your use of the Gemini CLI is governed by the
|
||||
[Google Cloud Platform Service Terms](https://cloud.google.com/terms/service-terms/).
|
||||
- Privacy Notice: The collection and use of your data is described in the
|
||||
[Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
|
||||
|
||||
## Usage statistics opt-out
|
||||
|
||||
You may opt-out from sending Gemini CLI Usage Statistics to Google by following
|
||||
the instructions available here:
|
||||
[Usage Statistics Configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md#usage-statistics).
|
||||
173
docs/resources/troubleshooting.md
Normal file
173
docs/resources/troubleshooting.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Troubleshooting guide
|
||||
|
||||
This guide provides solutions to common issues and debugging tips, including
|
||||
topics on:
|
||||
|
||||
- Authentication or login errors
|
||||
- Frequently asked questions (FAQs)
|
||||
- Debugging tips
|
||||
- Existing GitHub Issues similar to yours or creating new Issues
|
||||
|
||||
## Authentication or login errors
|
||||
|
||||
- **Error:
|
||||
`You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.`**
|
||||
- **Cause:** This error might occur if Gemini CLI detects the
|
||||
`GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` environment variable is
|
||||
defined. Setting these variables forces an organization subscription check.
|
||||
This might be an issue if you are using an individual Google account not
|
||||
linked to an organizational subscription.
|
||||
|
||||
- **Solution:**
|
||||
- **Individual Users:** Unset the `GOOGLE_CLOUD_PROJECT` and
|
||||
`GOOGLE_CLOUD_PROJECT_ID` environment variables. Check and remove these
|
||||
variables from your shell configuration files (for example, `.bashrc`,
|
||||
`.zshrc`) and any `.env` files. If this doesn't resolve the issue, try
|
||||
using a different Google account.
|
||||
|
||||
- **Organizational Users:** Contact your Google Cloud administrator to be
|
||||
added to your organization's Gemini Code Assist subscription.
|
||||
|
||||
- **Error:
|
||||
`Failed to login. Message: Your current account is not eligible... because it is not currently available in your location.`**
|
||||
- **Cause:** Gemini CLI does not currently support your location. For a full
|
||||
list of supported locations, see the following pages:
|
||||
- Gemini Code Assist for individuals:
|
||||
[Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
|
||||
|
||||
- **Error: `Failed to login. Message: Request contains an invalid argument`**
|
||||
- **Cause:** Users with Google Workspace accounts or Google Cloud accounts
|
||||
associated with their Gmail accounts may not be able to activate the free
|
||||
tier of the Google Code Assist plan.
|
||||
- **Solution:** For Google Cloud accounts, you can work around this by setting
|
||||
`GOOGLE_CLOUD_PROJECT` to your project ID. Alternatively, you can obtain the
|
||||
Gemini API key from
|
||||
[Google AI Studio](http://aistudio.google.com/app/apikey), which also
|
||||
includes a separate free tier.
|
||||
|
||||
- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or
|
||||
`unable to get local issuer certificate`**
|
||||
- **Cause:** You may be on a corporate network with a firewall that intercepts
|
||||
and inspects SSL/TLS traffic. This often requires a custom root CA
|
||||
certificate to be trusted by Node.js.
|
||||
- **Solution:** First try setting `NODE_USE_SYSTEM_CA`; if that does not
|
||||
resolve the issue, set `NODE_EXTRA_CA_CERTS`.
|
||||
- Set the `NODE_USE_SYSTEM_CA=1` environment variable to tell Node.js to use
|
||||
the operating system's native certificate store (where corporate
|
||||
certificates are typically already installed).
|
||||
- Example: `export NODE_USE_SYSTEM_CA=1`
|
||||
- Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of
|
||||
your corporate root CA certificate file.
|
||||
- Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`
|
||||
|
||||
## Common error messages and solutions
|
||||
|
||||
- **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**
|
||||
- **Cause:** Another process is already using the port that the MCP server is
|
||||
trying to bind to.
|
||||
- **Solution:** Either stop the other process that is using the port or
|
||||
configure the MCP server to use a different port.
|
||||
|
||||
- **Error: Command not found (when attempting to run Gemini CLI with
|
||||
`gemini`).**
|
||||
- **Cause:** Gemini CLI is not correctly installed or it is not in your
|
||||
system's `PATH`.
|
||||
- **Solution:** The update depends on how you installed Gemini CLI:
|
||||
- If you installed `gemini` globally, check that your `npm` global binary
|
||||
directory is in your `PATH`. You can update Gemini CLI using the command
|
||||
`npm install -g @google/gemini-cli@latest`.
|
||||
- If you are running `gemini` from source, ensure you are using the correct
|
||||
command to invoke it (e.g., `node packages/cli/dist/index.js ...`). To
|
||||
update Gemini CLI, pull the latest changes from the repository, and then
|
||||
rebuild using the command `npm run build`.
|
||||
|
||||
- **Error: `MODULE_NOT_FOUND` or import errors.**
|
||||
- **Cause:** Dependencies are not installed correctly, or the project hasn't
|
||||
been built.
|
||||
- **Solution:**
|
||||
1. Run `npm install` to ensure all dependencies are present.
|
||||
2. Run `npm run build` to compile the project.
|
||||
3. Verify that the build completed successfully with `npm run start`.
|
||||
|
||||
- **Error: "Operation not permitted", "Permission denied", or similar.**
|
||||
- **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations
|
||||
that are restricted by your sandbox configuration, such as writing outside
|
||||
the project directory or system temp directory.
|
||||
- **Solution:** Refer to the [Configuration: Sandboxing](./cli/sandbox.md)
|
||||
documentation for more information, including how to customize your sandbox
|
||||
configuration.
|
||||
|
||||
- **Gemini CLI is not running in interactive mode in "CI" environments**
|
||||
- **Issue:** The Gemini CLI does not enter interactive mode (no prompt
|
||||
appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`)
|
||||
is set. This is because the `is-in-ci` package, used by the underlying UI
|
||||
framework, detects these variables and assumes a non-interactive CI
|
||||
environment.
|
||||
- **Cause:** The `is-in-ci` package checks for the presence of `CI`,
|
||||
`CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix.
|
||||
When any of these are found, it signals that the environment is
|
||||
non-interactive, which prevents the Gemini CLI from starting in its
|
||||
interactive mode.
|
||||
- **Solution:** If the `CI_` prefixed variable is not needed for the CLI to
|
||||
function, you can temporarily unset it for the command. e.g.,
|
||||
`env -u CI_TOKEN gemini`
|
||||
|
||||
- **DEBUG mode not working from project .env file**
|
||||
- **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable
|
||||
debug mode for gemini-cli.
|
||||
- **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded
|
||||
from project `.env` files to prevent interference with gemini-cli behavior.
|
||||
- **Solution:** Use a `.gemini/.env` file instead, or configure the
|
||||
`advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer
|
||||
variables.
|
||||
|
||||
## Exit codes
|
||||
|
||||
The Gemini CLI uses specific exit codes to indicate the reason for termination.
|
||||
This is especially useful for scripting and automation.
|
||||
|
||||
| Exit Code | Error Type | Description |
|
||||
| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| 41 | `FatalAuthenticationError` | An error occurred during the authentication process. |
|
||||
| 42 | `FatalInputError` | Invalid or missing input was provided to the CLI. (non-interactive mode only) |
|
||||
| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt). |
|
||||
| 52 | `FatalConfigError` | A configuration file (`settings.json`) is invalid or contains errors. |
|
||||
| 53 | `FatalTurnLimitedError` | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
|
||||
|
||||
## Debugging tips
|
||||
|
||||
- **CLI debugging:**
|
||||
- Use the `--debug` flag for more detailed output. In interactive mode, press
|
||||
F12 to view the debug console.
|
||||
- Check the CLI logs, often found in a user-specific configuration or cache
|
||||
directory.
|
||||
|
||||
- **Core debugging:**
|
||||
- Check the server console output for error messages or stack traces.
|
||||
- Increase log verbosity if configurable. For example, set the `DEBUG_MODE`
|
||||
environment variable to `true` or `1`.
|
||||
- Use Node.js debugging tools (e.g., `node --inspect`) if you need to step
|
||||
through server-side code.
|
||||
|
||||
- **Tool issues:**
|
||||
- If a specific tool is failing, try to isolate the issue by running the
|
||||
simplest possible version of the command or operation the tool performs.
|
||||
- For `run_shell_command`, check that the command works directly in your shell
|
||||
first.
|
||||
- For _file system tools_, verify that paths are correct and check the
|
||||
permissions.
|
||||
|
||||
- **Pre-flight checks:**
|
||||
- Always run `npm run preflight` before committing code. This can catch many
|
||||
common issues related to formatting, linting, and type errors.
|
||||
|
||||
## Existing GitHub issues similar to yours or creating new issues
|
||||
|
||||
If you encounter an issue that was not covered here in this _Troubleshooting
|
||||
guide_, consider searching the Gemini CLI
|
||||
[Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues).
|
||||
If you can't find an issue similar to yours, consider creating a new GitHub
|
||||
Issue with a detailed description. Pull requests are also welcome!
|
||||
|
||||
> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
|
||||
> maintainers. We will not accept pull requests related to these issues.
|
||||
65
docs/resources/uninstall.md
Normal file
65
docs/resources/uninstall.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Uninstalling the CLI
|
||||
|
||||
Your uninstall method depends on how you ran the CLI. Follow the instructions
|
||||
for either npx or a global npm installation.
|
||||
|
||||
## Method 1: Using npx
|
||||
|
||||
npx runs packages from a temporary cache without a permanent installation. To
|
||||
"uninstall" the CLI, you must clear this cache, which will remove gemini-cli and
|
||||
any other packages previously executed with npx.
|
||||
|
||||
The npx cache is a directory named `_npx` inside your main npm cache folder. You
|
||||
can find your npm cache path by running `npm config get cache`.
|
||||
|
||||
**For macOS / Linux**
|
||||
|
||||
```bash
|
||||
# The path is typically ~/.npm/_npx
|
||||
rm -rf "$(npm config get cache)/_npx"
|
||||
```
|
||||
|
||||
**For Windows**
|
||||
|
||||
_Command Prompt_
|
||||
|
||||
```cmd
|
||||
:: The path is typically %LocalAppData%\npm-cache\_npx
|
||||
rmdir /s /q "%LocalAppData%\npm-cache\_npx"
|
||||
```
|
||||
|
||||
_PowerShell_
|
||||
|
||||
```powershell
|
||||
# The path is typically $env:LocalAppData\npm-cache\_npx
|
||||
Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
|
||||
```
|
||||
|
||||
## Method 2: Using npm (global install)
|
||||
|
||||
If you installed the CLI globally (e.g., `npm install -g @google/gemini-cli`),
|
||||
use the `npm uninstall` command with the `-g` flag to remove it.
|
||||
|
||||
```bash
|
||||
npm uninstall -g @google/gemini-cli
|
||||
```
|
||||
|
||||
This command completely removes the package from your system.
|
||||
|
||||
## Method 3: Homebrew
|
||||
|
||||
If you installed the CLI globally using Homebrew (e.g.,
|
||||
`brew install gemini-cli`), use the `brew uninstall` command to remove it.
|
||||
|
||||
```bash
|
||||
brew uninstall gemini-cli
|
||||
```
|
||||
|
||||
## Method 4: MacPorts
|
||||
|
||||
If you installed the CLI globally using MacPorts (e.g.,
|
||||
`sudo port install gemini-cli`), use the `port uninstall` command to remove it.
|
||||
|
||||
```bash
|
||||
sudo port uninstall gemini-cli
|
||||
```
|
||||
Reference in New Issue
Block a user