From d24e5cf3534acc22c371a8952cf11ede88290d48 Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:55:25 -0800 Subject: [PATCH] docs: Update 4 files (#13628) Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/get-started/authentication.md | 346 ++++++++++++++++------------- docs/get-started/index.md | 11 +- docs/quota-and-pricing.md | 30 ++- docs/troubleshooting.md | 30 ++- 4 files changed, 237 insertions(+), 180 deletions(-) diff --git a/docs/get-started/authentication.md b/docs/get-started/authentication.md index 404aa9d505..6e2ce5ca05 100644 --- a/docs/get-started/authentication.md +++ b/docs/get-started/authentication.md @@ -1,206 +1,198 @@ # Gemini CLI authentication setup -Gemini CLI requires authentication using Google's services. Before using Gemini -CLI, configure **one** of the following authentication methods: +To use Gemini CLI, you'll need to authenticate with Google. This guide helps you +quickly find the best way to sign in based on your account type and how you're +using the CLI. -- Interactive mode: - - Recommended: Login with Google - - Use Gemini API key - - Use Vertex AI -- Headless (non-interactive) mode -- Google Cloud Environments (Cloud Shell, Compute Engine, etc.) +For most users, we recommend starting Gemini CLI and logging in with your +personal Google account. -## Quick check: Running in Google Cloud Shell? +## Choose your authentication method -If you are running the Gemini CLI within a Google Cloud Shell environment, -authentication is typically automatic using your Cloud Shell credentials. +Select the authentication method that matches your situation in the table below: -### 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
[Vertex AI](#vertex-ai) | No (for Gemini API Key)
[Yes](#set-gcp) (for Vertex AI) | -Some other Google Cloud environments, such as Compute Engine VMs, might also -support automatic authentication. In these environments, Gemini CLI can -automatically use Application Default Credentials (ADC) sourced from the -environment's metadata server. +### What is my Google account type? -If automatic authentication does not occur in your environment, you will need to -use one of the interactive methods described below. +- **Individual Google accounts:** Includes all + [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 -following options: +## (Recommended) Login with Google -```bash -> 1. Login with Google -> 2. Use Gemini API key -> 3. Vertex AI -``` +If you run Gemini CLI on your local machine, the simplest authentication method +is logging in with your Google account. This method requires a web browser on a +machine that can communicate with the terminal running Gemini CLI (e.g., your +local machine). -The following sections provide instructions for each of these authentication -options. +> **Important:** If you are a **Google AI Pro** or **Google AI Ultra** +> 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 -logging in with your Google account. +1. Start the CLI: -> **Important:** Use this method if you are a **Google AI Pro** or **Google AI -> Ultra** subscriber. + ```bash + gemini + ``` -1. Select **Login with Google**. Gemini CLI will open a login prompt using your - web browser. +2. Select **Login with Google**. Gemini CLI opens a login prompt using your web + 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 - the Google account associated with your subscription. +### Do I need to set my Google Cloud project? -2. Follow the on-screen instructions. Your credentials will be cached locally - for future sessions. +Most individual Google accounts (free and paid) don't require a Google Cloud +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 - > communicate with the terminal running the CLI (e.g., your local machine). - > The browser will be redirected to a `localhost` URL that the CLI listens on - > during setup. +- 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. -#### (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 -`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 +## Use Gemini API key If you don't want to authenticate using your Google account, you can use an API key from Google AI Studio. -1. Obtain your API key from - [Google AI Studio](https://aistudio.google.com/app/apikey). -2. Set the `GEMINI_API_KEY` environment variable: +To authenticate and use Gemini CLI with a Gemini API key: - ```bash - # Replace YOUR_GEMINI_API_KEY with the key from AI Studio - export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" - ``` +1. Obtain your API key from + [Google AI Studio](https://aistudio.google.com/app/apikey). -To make this setting persistent, see -[Persisting Environment Variables](#persisting-environment-variables). +2. Set the `GEMINI_API_KEY` environment variable to your key. For example: + + ```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 > credentials. Protect them to prevent unauthorized access and potential misuse > of the service under your account. -### Use Vertex AI +## Use Vertex AI -If you intend to use Google Cloud's Vertex AI platform, you have several -authentication options: +To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the +following authentication options: -- Application Default Credentials (ADC) and `gcloud`. -- A Service Account JSON key. -- A Google Cloud API key. +- A. Application Default Credentials (ADC) using `gcloud`. +- B. Service account JSON 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 -following variables: `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and -`GOOGLE_CLOUD_LOCATION`. - -To set these variables: +For example: ```bash # 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_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` -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 > must unset them to use ADC: +> +> ```bash +> unset GOOGLE_API_KEY GEMINI_API_KEY +> ``` -```bash -unset GOOGLE_API_KEY GEMINI_API_KEY -``` +1. Verify you have a Google Cloud project and Vertex AI API is enabled. -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 - gcloud auth application-default login - ``` + ```bash + gcloud auth application-default login + ``` - See - [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) - for details. +3. [Configure your Google Cloud Project](#set-gcp). -3. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and - `GOOGLE_CLOUD_LOCATION` are set. +4. Start the CLI: + + ```bash + gemini + ``` + +5. Select **Vertex AI**. #### B. Vertex AI - service account JSON key -Consider this method of authentication in non-interactive environments, CI/CD, -or if your organization restricts user-based ADC or API key creation. +Consider this method of authentication in non-interactive environments, CI/CD +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 > must unset them: - -```bash -unset GOOGLE_API_KEY GEMINI_API_KEY -``` +> +> ```bash +> unset GOOGLE_API_KEY GEMINI_API_KEY +> ``` 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 service account. + 2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON - file's absolute path: + file's absolute path. For example: ```bash # Replace /path/to/your/keyfile.json with the actual path export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" ``` -3. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and - `GOOGLE_CLOUD_LOCATION` are set. +3. [Configure your Google Cloud Project](#set-gcp). -> **Warning:** Protect your service account key file as it provides access to -> your resources. +4. Start the CLI: + + ```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 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). + 2. Set the `GOOGLE_API_KEY` environment variable: ```bash @@ -210,17 +202,59 @@ unset GOOGLE_API_KEY GEMINI_API_KEY > **Note:** If you see errors like > `"API keys are not supported by this API..."`, your organization might - > restrict API key usage for this service. Try the - > [Service Account JSON Key](#b-vertex-ai-service-account-json-key) or - > [ADC](#a-vertex-ai-application-default-credentials-adc-using-gcloud) - > methods instead. + > restrict API key usage for this service. Try the other Vertex AI + > authentication methods instead. -To make any of these Vertex AI environment variable settings persistent, see -[Persisting Environment Variables](#persisting-environment-variables). +3. [Configure your Google Cloud Project](#set-gcp). -## 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 + +> **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 + +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 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 ``` - > **Warning:** Be advised that when you export API keys or service account - > paths in your shell configuration file, any process executed from the - > shell can potentially read them. + > **Warning:** Be aware that when you export API keys or service account + > paths in your shell configuration file, any process launched from that + > shell can read them. 2. **Use a `.env` file:** Create a `.gemini/.env` file in your project 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 ``` - 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 -Non-interactive mode / headless environments will use your existing -authentication method, if an existing authentication credential is cached. +When running Gemini CLI within certain Google Cloud environments, authentication +is automatic. -If you have not already logged in with an authentication credential (such as a -Google account), you **must** configure authentication using environment -variables: +In a Google Cloud Shell environment, Gemini CLI typically authenticates +automatically using your Cloud Shell credentials. In Compute Engine +environments, Gemini CLI automatically uses Application Default Credentials +(ADC) from the environment's metadata server. -1. **Gemini API key:** Set `GEMINI_API_KEY`. -2. **Vertex AI:** - - 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`. +If automatic authentication fails, use one of the interactive methods described +on this page. -The CLI will exit with an error in non-interactive mode if no suitable -environment variables are found. +## Running in headless mode + +[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? diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 21a79f4cf6..093b3c01b4 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -28,19 +28,24 @@ For more installation options, see [Gemini CLI Installation](./installation.md). ## Authenticate -To begin using Gemini CLI, you must authenticate with a Google service. The most -straightforward authentication method uses your existing Google account: +To begin using Gemini CLI, you must authenticate with a Google service. In most +cases, you can log in with your existing Google account: 1. Run Gemini CLI after installation: + ```bash gemini ``` + 2. When asked "How would you like to authenticate for this project?" select **1. Login with Google**. + 3. Select your Google account. + 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). ## Configure diff --git a/docs/quota-and-pricing.md b/docs/quota-and-pricing.md index 4c845da79c..7b1b37a32c 100644 --- a/docs/quota-and-pricing.md +++ b/docs/quota-and-pricing.md @@ -1,20 +1,17 @@ # Gemini CLI: Quotas and pricing -Gemini CLI offers a generous free tier that covers the use cases for many -individual developers. For enterprise / professional usage, or if you need -higher limits, there are multiple possible avenues depending on what type of -account you use to authenticate. +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 Privacy policy and +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. +> **Note:** Published prices are list price; additional negotiated commercial +> discounting may apply. -This article outlines the specific quotas and pricing applicable to the Gemini -CLI when using different authentication methods. +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: @@ -72,11 +69,9 @@ Learn more at 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://cloud.google.com/products/gemini/pricing) - by signing up at - [Set up Gemini Code Assist](https://goo.gle/set-up-gemini-code-assist). This - is recommended for individual developers. Quotas and pricing are based on a - fixed price subscription. +- [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. @@ -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) 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 license seats. For predictable costs, you can sign in with Google. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 360852b2ca..4539a00bf9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -10,13 +10,31 @@ topics on: ## 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`** - - 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. - - 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 + - **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.