chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,188 @@
|
||||
# Frequently asked questions (FAQ)
|
||||
|
||||
This page provides answers to common questions and solutions to frequent
|
||||
problems encountered while using Gemini CLI.
|
||||
|
||||
## General issues
|
||||
|
||||
This section addresses common questions about Gemini CLI usage, security, and
|
||||
troubleshooting general errors.
|
||||
|
||||
### Why can't I use third-party software like Claude Code, OpenClaw, or OpenCode with Gemini CLI?
|
||||
|
||||
Using third-party software, tools, or services to harvest or piggyback on Gemini
|
||||
CLI's OAuth authentication to access our backend services is a direct violation
|
||||
of our [applicable terms and policies](tos-privacy.md). Doing so bypasses our
|
||||
intended authentication and security structures, and such actions may be grounds
|
||||
for immediate suspension or termination of your account. If you would like to
|
||||
use a third-party coding agent with Gemini, the supported and secure method is
|
||||
to use a Vertex AI or Google AI Studio API key.
|
||||
|
||||
### 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 check which version of Gemini CLI I'm currently running?
|
||||
|
||||
You can check your current Gemini CLI version using one of these methods:
|
||||
|
||||
- Run `gemini --version` or `gemini -v` from your terminal
|
||||
- Check the globally installed version using your package manager:
|
||||
- npm: `npm list -g @google/gemini-cli`
|
||||
- pnpm: `pnpm list -g @google/gemini-cli`
|
||||
- yarn: `yarn global list @google/gemini-cli`
|
||||
- bun: `bun pm ls -g @google/gemini-cli`
|
||||
- homebrew: `brew list --versions gemini-cli`
|
||||
- Inside an active Gemini CLI session, use the `/about` command
|
||||
|
||||
### 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:
|
||||
|
||||
**macOS/Linux**
|
||||
|
||||
```bash
|
||||
export GOOGLE_CLOUD_PROJECT="your-project-id"
|
||||
```
|
||||
|
||||
**Windows (PowerShell)**
|
||||
|
||||
```powershell
|
||||
$env:GOOGLE_CLOUD_PROJECT="your-project-id"
|
||||
```
|
||||
|
||||
To make this setting permanent, add this line to your shell's startup file (for
|
||||
example, `~/.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 Gemini CLI configuration and settings files stored?
|
||||
|
||||
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](../reference/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)
|
||||
@@ -0,0 +1,214 @@
|
||||
# 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 increased quota,
|
||||
several options are available depending on your authentication account type.
|
||||
|
||||
For a high-level comparison of available subscriptions and to select the right
|
||||
quota for your needs, see the [Plans page](https://geminicli.com/plans/).
|
||||
|
||||
## Overview
|
||||
|
||||
This article outlines the specific quotas and pricing applicable to Gemini CLI
|
||||
when using different authentication methods.
|
||||
|
||||
The following table summarizes the available quotas and their respective limits:
|
||||
|
||||
| Authentication method | Tier / Subscription | Maximum requests per user per day |
|
||||
| :-------------------- | :------------------------------ | :-------------------------------- |
|
||||
| **Google account** | Gemini Code Assist (Individual) | 1,000 requests |
|
||||
| | Google AI Pro | 1,500 requests |
|
||||
| | Google AI Ultra | 2,000 requests |
|
||||
| **Gemini API key** | Free tier (Unpaid) | 250 requests |
|
||||
| | Pay-as-you-go (Paid) | Varies |
|
||||
| **Vertex AI** | Express mode (Free) | Varies |
|
||||
| | Pay-as-you-go (Paid) | Varies |
|
||||
| **Google Workspace** | Code Assist Standard | 1,500 requests |
|
||||
| | Code Assist Enterprise | 2,000 requests |
|
||||
| | Workspace AI Ultra | 2,000 requests |
|
||||
|
||||
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.
|
||||
|
||||
Requests are limited per user per minute and are subject to the availability of
|
||||
the service in times of high demand.
|
||||
|
||||
## Free usage
|
||||
|
||||
Access to Gemini CLI begins with a generous free tier, perfect for
|
||||
experimentation and light use.
|
||||
|
||||
Your free usage is governed by the following limits, which 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 maximum model requests / user / day
|
||||
- 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 maximum model requests / user / day
|
||||
- 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 specific to your account and their limits vary.
|
||||
|
||||
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:
|
||||
|
||||
### Individuals
|
||||
|
||||
These tiers apply when you sign in with a personal account. To verify whether
|
||||
you're on a personal account, visit
|
||||
[Google One](https://one.google.com/about/plans?hl=en-US&g1_landing_page=0):
|
||||
|
||||
- If you are on a personal account, you will see your personal dashboard.
|
||||
- If you are not on a personal account, you will see: "You're currently signed
|
||||
in to your Google Workspace Account."
|
||||
|
||||
**Supported tiers:** _- Tiers not listed above, including Google AI Plus, are
|
||||
not supported._
|
||||
|
||||
- [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)
|
||||
|
||||
### Through your organization
|
||||
|
||||
These tiers are applicable when you are signing in with a Google Workspace
|
||||
account.
|
||||
|
||||
- To verify your account type, visit
|
||||
[the Google One page](https://one.google.com/about/plans?hl=en-US&g1_landing_page=0).
|
||||
- You are on a workspace account if you see the message "You're currently signed
|
||||
in to your Google Workspace Account".
|
||||
|
||||
**Supported tiers:** _- Tiers not listed above, including Workspace AI
|
||||
Standard/Plus and AI Expanded, are not supported._
|
||||
|
||||
- [Workspace AI Ultra Access](https://workspace.google.com/products/ai-ultra/).
|
||||
- [Purchase a Gemini Code Assist Subscription through Google Cloud](https://cloud.google.com/gemini/docs/codeassist/overview).
|
||||
|
||||
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 the following request limits:
|
||||
|
||||
- Gemini Code Assist Standard edition:
|
||||
- 1500 maximum model requests / user / day
|
||||
- Gemini Code Assist Enterprise edition:
|
||||
- 2000 maximum model requests / user / day
|
||||
- Model requests will be made across the Gemini model family as determined by
|
||||
Gemini CLI.
|
||||
|
||||
[Learn more about Gemini Code Assist 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)
|
||||
|
||||
An enterprise-grade platform for building, deploying, and managing AI models,
|
||||
including Gemini. It offers enhanced security, data governance, and integration
|
||||
with other Google Cloud services.
|
||||
|
||||
- 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
|
||||
|
||||
Ideal for developers who want to quickly build applications with the Gemini
|
||||
models. This is the most direct way to use the models.
|
||||
|
||||
- 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 reaching a limit on your
|
||||
quota.
|
||||
|
||||
## 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.
|
||||
|
||||
## Check usage and limits
|
||||
|
||||
You can check your current token usage and applicable limits using the
|
||||
`/stats model` command. This command provides a snapshot of your current
|
||||
session's token usage, as well as information about the limits associated with
|
||||
your current quota.
|
||||
|
||||
For more information on the `/stats` command and its subcommands, see the
|
||||
[Command Reference](../reference/commands.md#stats).
|
||||
|
||||
A summary of model usage is also presented on exit at the end of a session.
|
||||
|
||||
## Tips to avoid high costs
|
||||
|
||||
When using a pay-as-you-go plan, be mindful of your usage to avoid unexpected
|
||||
costs.
|
||||
|
||||
- **Be selective with suggestions**: Before accepting a suggestion, especially
|
||||
for a computationally intensive task like refactoring a large codebase,
|
||||
consider if it's the most cost-effective approach.
|
||||
- **Use precise prompts**: You are paying per call, so think about the most
|
||||
efficient way to get your desired result. A well-crafted prompt can often get
|
||||
you the answer you need in a single call, rather than multiple back-and-forth
|
||||
interactions.
|
||||
- **Monitor your usage**: Use the `/stats model` command to track your token
|
||||
usage during a session. This can help you stay aware of your spending in real
|
||||
time.
|
||||
@@ -0,0 +1,104 @@
|
||||
# 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. 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.
|
||||
|
||||
Directly accessing the services powering Gemini CLI (for example, the Gemini
|
||||
Code Assist service) using third-party software, tools, or services (for
|
||||
example, using OpenClaw with Gemini CLI OAuth) is a violation of applicable
|
||||
terms and policies. Such actions may be grounds for suspension or termination of
|
||||
your account.
|
||||
|
||||
Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
|
||||
Policy.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
> [!NOTE]
|
||||
> See [quotas and pricing](quota-and-pricing.md) for the quota and
|
||||
> pricing details that apply to your usage of 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. 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 signed 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 signed 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 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 signed 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 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).
|
||||
@@ -0,0 +1,206 @@
|
||||
# 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 sign in. 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 sign in. 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` (Windows PowerShell:
|
||||
`$env: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`
|
||||
(Windows PowerShell:
|
||||
`$env:NODE_EXTRA_CA_CERTS="C:\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 (for example, `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:** Gemini CLI does not enter interactive mode (no prompt appears) if
|
||||
an environment variable starting with `CI_` (for example, `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 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. For example,
|
||||
`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.
|
||||
|
||||
- **Warning: `npm WARN deprecated node-domexception@1.0.0` or
|
||||
`npm WARN deprecated glob` during install/update**
|
||||
- **Issue:** When installing or updating Gemini CLI globally via
|
||||
`npm install -g @google/gemini-cli` or `npm update -g @google/gemini-cli`,
|
||||
you might see deprecation warnings regarding `node-domexception` or old
|
||||
versions of `glob`.
|
||||
- **Cause:** These warnings occur because some dependencies (or their
|
||||
sub-dependencies, like `google-auth-library`) rely on older package
|
||||
versions. Since Gemini CLI requires Node.js 20 or higher, the platform's
|
||||
native features (like the native `DOMException`) are used, making these
|
||||
warnings purely informational.
|
||||
- **Solution:** These warnings are harmless and can be safely ignored. Your
|
||||
installation or update will complete successfully and function properly
|
||||
without any action required.
|
||||
|
||||
## Exit codes
|
||||
|
||||
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 (for example, 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 (for example, `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 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!
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
> [!NOTE]
|
||||
> Issues tagged as "🔒Maintainers only" are reserved for project
|
||||
> maintainers. We will not accept pull requests related to these issues.
|
||||
@@ -0,0 +1,57 @@
|
||||
# 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 (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 (for example,
|
||||
`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 (for example,
|
||||
`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 (for example,
|
||||
`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