docs: Update 4 files (#13628)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
This commit is contained in:
g-samroberts
2025-12-01 15:55:25 -08:00
committed by GitHub
parent 70a48a3dd6
commit d24e5cf353
4 changed files with 237 additions and 180 deletions

View File

@@ -1,206 +1,198 @@
# Gemini CLI authentication setup # Gemini CLI authentication setup
Gemini CLI requires authentication using Google's services. Before using Gemini To use Gemini CLI, you'll need to authenticate with Google. This guide helps you
CLI, configure **one** of the following authentication methods: quickly find the best way to sign in based on your account type and how you're
using the CLI.
- Interactive mode: For most users, we recommend starting Gemini CLI and logging in with your
- Recommended: Login with Google personal Google account.
- Use Gemini API key
- Use Vertex AI
- Headless (non-interactive) mode
- Google Cloud Environments (Cloud Shell, Compute Engine, etc.)
## Quick check: Running in Google Cloud Shell? ## Choose your authentication method <a id="auth-methods"></a>
If you are running the Gemini CLI within a Google Cloud Shell environment, Select the authentication method that matches your situation in the table below:
authentication is typically automatic using your Cloud Shell credentials.
### Other Google Cloud environments (e.g., Compute Engine) | User Type / Scenario | Recommended Authentication Method | Google Cloud Project Required |
| :--------------------------------------------------------------------- | :--------------------------------------------------------------- | :---------------------------------------------------------- |
| Individual Google accounts | [Login with Google](#login-google) | No, with exceptions |
| Organization users with a company, school, or Google Workspace account | [Login with Google](#login-google) | [Yes](#set-gcp) |
| AI Studio user with a Gemini API key | [Use Gemini API Key](#gemini-api) | No |
| Google Cloud Vertex AI user | [Vertex AI](#vertex-ai) | [Yes](#set-gcp) |
| [Headless mode](#headless) | [Use Gemini API Key](#gemini-api) or<br> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br> [Yes](#set-gcp) (for Vertex AI) |
Some other Google Cloud environments, such as Compute Engine VMs, might also ### What is my Google account type?
support automatic authentication. In these environments, Gemini CLI can
automatically use Application Default Credentials (ADC) sourced from the
environment's metadata server.
If automatic authentication does not occur in your environment, you will need to - **Individual Google accounts:** Includes all
use one of the interactive methods described below. [free tier accounts](../quota-and-pricing/#free-usage) such as Gemini Code
Assist for individuals, as well as paid subscriptions for
[Google AI Pro and Ultra](https://gemini.google/subscriptions/).
## Authenticate in interactive mode - **Organization accounts:** Accounts using paid licenses through an
organization such as a company, school, or
[Google Workspace](https://workspace.google.com/). Includes
[Google AI Ultra for Business](https://support.google.com/a/answer/16345165)
subscriptions.
When you run Gemini CLI through the command-line, Gemini CLI will provide the ## (Recommended) Login with Google <a id="login-google"></a>
following options:
```bash If you run Gemini CLI on your local machine, the simplest authentication method
> 1. Login with Google is logging in with your Google account. This method requires a web browser on a
> 2. Use Gemini API key machine that can communicate with the terminal running Gemini CLI (e.g., your
> 3. Vertex AI local machine).
```
The following sections provide instructions for each of these authentication > **Important:** If you are a **Google AI Pro** or **Google AI Ultra**
options. > subscriber, use the Google account associated with your subscription.
### Recommended: Login with Google To authenticate and use Gemini CLI:
If you are running Gemini CLI on your local machine, the simplest method is 1. Start the CLI:
logging in with your Google account.
> **Important:** Use this method if you are a **Google AI Pro** or **Google AI ```bash
> Ultra** subscriber. gemini
```
1. Select **Login with Google**. Gemini CLI will open a login prompt using your 2. Select **Login with Google**. Gemini CLI opens a login prompt using your web
web browser. browser. Follow the on-screen instructions. Your credentials will be cached
locally for future sessions.
If you are a **Google AI Pro** or **Google AI Ultra** subscriber, login with ### Do I need to set my Google Cloud project?
the Google account associated with your subscription.
2. Follow the on-screen instructions. Your credentials will be cached locally Most individual Google accounts (free and paid) don't require a Google Cloud
for future sessions. project for authentication. However, you'll need to set a Google Cloud project
when you meet at least one of the following conditions:
> **Note:** This method requires a web browser on a machine that can - You are using a company, school, or Google Workspace account.
> communicate with the terminal running the CLI (e.g., your local machine). - You are using a Gemini Code Assist license from the Google Developer Program.
> The browser will be redirected to a `localhost` URL that the CLI listens on - You are using a license from a Gemini Code Assist subscription.
> during setup.
#### (Optional) Set your Google Cloud project For instructions, see [Set your Google Cloud Project](#set-gcp).
When you log in using a Google account, you may be prompted to select a ## Use Gemini API key <a id="gemini-api"></a>
`GOOGLE_CLOUD_PROJECT`.
This can be necessary if you are:
- Using a Google Workspace account.
- Using a Gemini Code Assist license from the Google Developer Program.
- Using a license from a Gemini Code Assist subscription.
- Using the product outside the
[supported regions](https://developers.google.com/gemini-code-assist/resources/available-locations)
for free individual usage.
- A Google account holder under the age of 18.
If you fall into one of these categories, you must:
1. Have a Google Cloud Project ID.
2. [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api).
3. [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam).
To set the project ID, you can export either the `GOOGLE_CLOUD_PROJECT` or
`GOOGLE_CLOUD_PROJECT_ID` environment variable. The CLI checks for
`GOOGLE_CLOUD_PROJECT` first, then falls back to `GOOGLE_CLOUD_PROJECT_ID` :
```bash
# Replace YOUR_PROJECT_ID with your actual Google Cloud Project ID
# Using the standard variable:
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
# Or, using the fallback variable:
export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"
```
To make this setting persistent, see
[Persisting Environment Variables](#persisting-environment-variables).
### Use Gemini API key
If you don't want to authenticate using your Google account, you can use an API If you don't want to authenticate using your Google account, you can use an API
key from Google AI Studio. key from Google AI Studio.
1. Obtain your API key from To authenticate and use Gemini CLI with a Gemini API key:
[Google AI Studio](https://aistudio.google.com/app/apikey).
2. Set the `GEMINI_API_KEY` environment variable:
```bash 1. Obtain your API key from
# Replace YOUR_GEMINI_API_KEY with the key from AI Studio [Google AI Studio](https://aistudio.google.com/app/apikey).
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
To make this setting persistent, see 2. Set the `GEMINI_API_KEY` environment variable to your key. For example:
[Persisting Environment Variables](#persisting-environment-variables).
```bash
# Replace YOUR_GEMINI_API_KEY with the key from AI Studio
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
To make this setting persistent, see
[Persisting Environment Variables](#persisting-vars).
3. Start the CLI:
```bash
gemini
```
4. Select **Use Gemini API key**.
> **Warning:** Treat API keys, especially for services like Gemini, as sensitive > **Warning:** Treat API keys, especially for services like Gemini, as sensitive
> credentials. Protect them to prevent unauthorized access and potential misuse > credentials. Protect them to prevent unauthorized access and potential misuse
> of the service under your account. > of the service under your account.
### Use Vertex AI ## Use Vertex AI <a id="vertex-ai"></a>
If you intend to use Google Cloud's Vertex AI platform, you have several To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the
authentication options: following authentication options:
- Application Default Credentials (ADC) and `gcloud`. - A. Application Default Credentials (ADC) using `gcloud`.
- A Service Account JSON key. - B. Service account JSON key.
- A Google Cloud API key. - C. Google Cloud API key.
#### First: Set required environment variables Regardless of your authentication method for Vertex AI, you'll need to set
`GOOGLE_CLOUD_PROJECT` to your Google Cloud project ID with the Vertex AI API
enabled, and `GOOGLE_CLOUD_LOCATION` to the location of your Vertex AI resources
or the location where you want to run your jobs.
Regardless of your method of authentication, you'll typically need to set the For example:
following variables: `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and
`GOOGLE_CLOUD_LOCATION`.
To set these variables:
```bash ```bash
# Replace with your project ID and desired location (e.g., us-central1) # Replace with your project ID and desired location (e.g., us-central1)
# You can use GOOGLE_CLOUD_PROJECT_ID as a fallback for GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
``` ```
To make any Vertex AI environment variable settings persistent, see
[Persisting Environment Variables](#persisting-vars).
#### A. Vertex AI - application default credentials (ADC) using `gcloud` #### A. Vertex AI - application default credentials (ADC) using `gcloud`
Consider this method of authentication if you have Google Cloud CLI installed. Consider this authentication method if you have Google Cloud CLI installed.
> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you > **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you
> must unset them to use ADC: > must unset them to use ADC:
>
> ```bash
> unset GOOGLE_API_KEY GEMINI_API_KEY
> ```
```bash 1. Verify you have a Google Cloud project and Vertex AI API is enabled.
unset GOOGLE_API_KEY GEMINI_API_KEY
```
1. Ensure you have a Google Cloud project and Vertex AI API is enabled. 2. Log in to Google Cloud:
2. Log in to Google Cloud:
```bash ```bash
gcloud auth application-default login gcloud auth application-default login
``` ```
See 3. [Configure your Google Cloud Project](#set-gcp).
[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
for details.
3. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and 4. Start the CLI:
`GOOGLE_CLOUD_LOCATION` are set.
```bash
gemini
```
5. Select **Vertex AI**.
#### B. Vertex AI - service account JSON key #### B. Vertex AI - service account JSON key
Consider this method of authentication in non-interactive environments, CI/CD, Consider this method of authentication in non-interactive environments, CI/CD
or if your organization restricts user-based ADC or API key creation. pipelines, or if your organization restricts user-based ADC or API key creation.
> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you > **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you
> must unset them: > must unset them:
>
```bash > ```bash
unset GOOGLE_API_KEY GEMINI_API_KEY > unset GOOGLE_API_KEY GEMINI_API_KEY
``` > ```
1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete) 1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete)
and download the provided JSON file. Assign the "Vertex AI User" role to the and download the provided JSON file. Assign the "Vertex AI User" role to the
service account. service account.
2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON 2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON
file's absolute path: file's absolute path. For example:
```bash ```bash
# Replace /path/to/your/keyfile.json with the actual path # Replace /path/to/your/keyfile.json with the actual path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
``` ```
3. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and 3. [Configure your Google Cloud Project](#set-gcp).
`GOOGLE_CLOUD_LOCATION` are set.
> **Warning:** Protect your service account key file as it provides access to 4. Start the CLI:
> your resources.
```bash
gemini
```
5. Select **Vertex AI**.
> **Warning:** Protect your service account key file as it gives access to
> your resources.
#### C. Vertex AI - Google Cloud API key #### C. Vertex AI - Google Cloud API key
1. Obtain a Google Cloud API key: 1. Obtain a Google Cloud API key:
[Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser). [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser).
2. Set the `GOOGLE_API_KEY` environment variable: 2. Set the `GOOGLE_API_KEY` environment variable:
```bash ```bash
@@ -210,17 +202,59 @@ unset GOOGLE_API_KEY GEMINI_API_KEY
> **Note:** If you see errors like > **Note:** If you see errors like
> `"API keys are not supported by this API..."`, your organization might > `"API keys are not supported by this API..."`, your organization might
> restrict API key usage for this service. Try the > restrict API key usage for this service. Try the other Vertex AI
> [Service Account JSON Key](#b-vertex-ai-service-account-json-key) or > authentication methods instead.
> [ADC](#a-vertex-ai-application-default-credentials-adc-using-gcloud)
> methods instead.
To make any of these Vertex AI environment variable settings persistent, see 3. [Configure your Google Cloud Project](#set-gcp).
[Persisting Environment Variables](#persisting-environment-variables).
## Persisting environment variables 4. Start the CLI:
To avoid setting environment variables in every terminal session, you can: ```bash
gemini
```
5. Select **Vertex AI**.
## Set your Google Cloud project <a id="set-gcp"></a>
> **Important:** Most individual Google accounts (free and paid) don't require a
> Google Cloud project for authentication.
When you sign in using your Google account, you may need to configure a Google
Cloud project for Gemini CLI to use. This applies when you meet at least one of
the following conditions:
- You are using a Company, School, or Google Workspace account.
- You are using a Gemini Code Assist license from the Google Developer Program.
- You are using a license from a Gemini Code Assist subscription.
To configure Gemini CLI to use a Google Cloud project, do the following:
1. [Find your Google Cloud Project ID](https://support.google.com/googleapi/answer/7014113).
2. [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api).
3. [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam).
4. Configure your environment variables. Set either the `GOOGLE_CLOUD_PROJECT`
or `GOOGLE_CLOUD_PROJECT_ID` variable to the project ID to use with Gemini
CLI. Gemini CLI checks for `GOOGLE_CLOUD_PROJECT` first, then falls back to
`GOOGLE_CLOUD_PROJECT_ID`.
For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable:
```bash
# Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
```
To make this setting persistent, see
[Persisting Environment Variables](#persisting-vars).
## Persisting environment variables <a id="persisting-vars"></a>
To avoid setting environment variables for every terminal session, you can
persist them with the following methods:
1. **Add your environment variables to your shell configuration file:** Append 1. **Add your environment variables to your shell configuration file:** Append
the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`, the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`,
@@ -233,9 +267,9 @@ To avoid setting environment variables in every terminal session, you can:
source ~/.bashrc source ~/.bashrc
``` ```
> **Warning:** Be advised that when you export API keys or service account > **Warning:** Be aware that when you export API keys or service account
> paths in your shell configuration file, any process executed from the > paths in your shell configuration file, any process launched from that
> shell can potentially read them. > shell can read them.
2. **Use a `.env` file:** Create a `.gemini/.env` file in your project 2. **Use a `.env` file:** Create a `.gemini/.env` file in your project
directory or home directory. Gemini CLI automatically loads variables from directory or home directory. Gemini CLI automatically loads variables from
@@ -252,27 +286,31 @@ To avoid setting environment variables in every terminal session, you can:
EOF EOF
``` ```
Variables are loaded from the first file found, not merged. Variables are loaded from the first file found, not merged.
## Non-interactive mode / headless environments ## Running in Google Cloud environments <a id="cloud-env"></a>
Non-interactive mode / headless environments will use your existing When running Gemini CLI within certain Google Cloud environments, authentication
authentication method, if an existing authentication credential is cached. is automatic.
If you have not already logged in with an authentication credential (such as a In a Google Cloud Shell environment, Gemini CLI typically authenticates
Google account), you **must** configure authentication using environment automatically using your Cloud Shell credentials. In Compute Engine
variables: environments, Gemini CLI automatically uses Application Default Credentials
(ADC) from the environment's metadata server.
1. **Gemini API key:** Set `GEMINI_API_KEY`. If automatic authentication fails, use one of the interactive methods described
2. **Vertex AI:** on this page.
- Set `GOOGLE_GENAI_USE_VERTEXAI=true`.
- **With Google Cloud API Key:** Set `GOOGLE_API_KEY`.
- **With ADC:** Ensure ADC is configured (e.g., via a service account with
`GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` (or
`GOOGLE_CLOUD_PROJECT_ID`) and `GOOGLE_CLOUD_LOCATION`.
The CLI will exit with an error in non-interactive mode if no suitable ## Running in headless mode <a id="headless"></a>
environment variables are found.
[Headless mode](../cli/headless) will use your existing authentication method,
if an existing authentication credential is cached.
If you have not already logged in with an authentication credential, you must
configure authentication using environment variables:
- [Use Gemini API Key](#gemini-api)
- [Vertex AI](#vertex-ai)
## What's next? ## What's next?

View File

@@ -28,19 +28,24 @@ For more installation options, see [Gemini CLI Installation](./installation.md).
## Authenticate ## Authenticate
To begin using Gemini CLI, you must authenticate with a Google service. The most To begin using Gemini CLI, you must authenticate with a Google service. In most
straightforward authentication method uses your existing Google account: cases, you can log in with your existing Google account:
1. Run Gemini CLI after installation: 1. Run Gemini CLI after installation:
```bash ```bash
gemini gemini
``` ```
2. When asked "How would you like to authenticate for this project?" select **1. 2. When asked "How would you like to authenticate for this project?" select **1.
Login with Google**. Login with Google**.
3. Select your Google account. 3. Select your Google account.
4. Click on **Sign in**. 4. Click on **Sign in**.
For other authentication options and information, see Certain account types may require you to configure a Google Cloud project. For
more information, including other authentication methods, see
[Gemini CLI Authentication Setup](./authentication.md). [Gemini CLI Authentication Setup](./authentication.md).
## Configure ## Configure

View File

@@ -1,20 +1,17 @@
# Gemini CLI: Quotas and pricing # Gemini CLI: Quotas and pricing
Gemini CLI offers a generous free tier that covers the use cases for many Gemini CLI offers a generous free tier that covers many individual developers'
individual developers. For enterprise / professional usage, or if you need use cases. For enterprise or professional usage, or if you need higher limits,
higher limits, there are multiple possible avenues depending on what type of several options are available depending on your authentication account type.
account you use to authenticate.
See [privacy and terms](./tos-privacy.md) for details on Privacy policy and See [privacy and terms](./tos-privacy.md) for details on the Privacy Policy and
Terms of Service. Terms of Service.
> [!NOTE] > **Note:** Published prices are list price; additional negotiated commercial
> > discounting may apply.
> Published prices are list price; additional negotiated commercial discounting
> may apply.
This article outlines the specific quotas and pricing applicable to the Gemini This article outlines the specific quotas and pricing applicable to Gemini CLI
CLI when using different authentication methods. when using different authentication methods.
Generally, there are three categories to choose from: Generally, there are three categories to choose from:
@@ -72,11 +69,9 @@ Learn more at
If you use up your initial number of requests, you can continue to benefit from 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: Gemini CLI by upgrading to one of the following subscriptions:
- [Google AI Pro and AI Ultra](https://cloud.google.com/products/gemini/pricing) - [Google AI Pro and AI Ultra](https://gemini.google/subscriptions/). This is
by signing up at recommended for individual developers. Quotas and pricing are based on a fixed
[Set up Gemini Code Assist](https://goo.gle/set-up-gemini-code-assist). This price subscription.
is recommended for individual developers. Quotas and pricing are based on a
fixed price subscription.
For predictable costs, you can log in with Google. For predictable costs, you can log in with Google.
@@ -85,7 +80,8 @@ Gemini CLI by upgrading to one of the following subscriptions:
- [Purchase a Gemini Code Assist Subscription through Google Cloud ](https://cloud.google.com/gemini/docs/codeassist/overview) - [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 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) [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 Quotas and pricing are based on a fixed price subscription with assigned
license seats. For predictable costs, you can sign in with Google. license seats. For predictable costs, you can sign in with Google.

View File

@@ -10,13 +10,31 @@ topics on:
## Authentication or login errors ## 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: Request contains an invalid argument`** - **Error: `Failed to login. Message: Request contains an invalid argument`**
- Users with Google Workspace accounts or Google Cloud accounts associated - **Cause:** Users with Google Workspace accounts or Google Cloud accounts
with their Gmail accounts may not be able to activate the free tier of the associated with their Gmail accounts may not be able to activate the free
Google Code Assist plan. tier of the Google Code Assist plan.
- For Google Cloud accounts, you can work around this by setting - **Solution:** For Google Cloud accounts, you can work around this by setting
`GOOGLE_CLOUD_PROJECT` to your project ID. `GOOGLE_CLOUD_PROJECT` to your project ID. Alternatively, you can obtain the
- Alternatively, you can obtain the Gemini API key from Gemini API key from
[Google AI Studio](http://aistudio.google.com/app/apikey), which also [Google AI Studio](http://aistudio.google.com/app/apikey), which also
includes a separate free tier. includes a separate free tier.