MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

cleanup(markdown): Prettier format all markdown @ 80 char width (#10714)

Browse Source
This commit is contained in:
Richie Foreman
2025-10-09 08:17:37 -04:00
committed by GitHub
parent 0cd490a9b8
commit a08938010c
60 changed files with 4796 additions and 1733 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/get-started/authentication.md
View File

@@ -1,6 +1,7 @@
# Gemini CLI Authentication Setup
Gemini CLI requires authentication using Google's services. Before using Gemini CLI, configure **one** of the following authentication methods:
Gemini CLI requires authentication using Google's services. Before using Gemini
CLI, configure **one** of the following authentication methods:
- Interactive mode:
- Recommended: Login with Google
@@ -11,11 +12,13 @@ Gemini CLI requires authentication using Google's services. Before using Gemini
## Quick Check: Running in Google Cloud Shell?
If you are running the Gemini CLI within a Google Cloud Shell environment, authentication is typically automatic using your Cloud Shell credentials.
If you are running the Gemini CLI within a Google Cloud Shell environment,
authentication is typically automatic using your Cloud Shell credentials.
## Authenticate in Interactive mode
When you run Gemini CLI through the command-line, Gemini CLI will provide the following options:
When you run Gemini CLI through the command-line, Gemini CLI will provide the
following options:
```bash
> 1. Login with Google
@@ -23,32 +26,44 @@ When you run Gemini CLI through the command-line, Gemini CLI will provide the fo
> 3. Vertex AI
```
The following sections provide instructions for each of these authentication options.
The following sections provide instructions for each of these authentication
options.
### Recommended: Login with Google
If you are running Gemini CLI on your local machine, the simplest method is logging in with your Google account.
If you are running Gemini CLI on your local machine, the simplest method is
logging in with your Google account.
> **Important:** Use this method if you are a **Google AI Pro** or **Google AI Ultra** subscriber.
> **Important:** Use this method if you are a **Google AI Pro** or **Google AI
> Ultra** subscriber.
1. Select **Login with Google**. Gemini CLI will open a login prompt using your web browser.
1. Select **Login with Google**. Gemini CLI will open a login prompt using your
web browser.
If you are a **Google AI Pro** or **Google AI Ultra** subscriber, login with the Google account associated with your subscription.
If you are a **Google AI Pro** or **Google AI Ultra** subscriber, login with
the Google account associated with your subscription.
2. Follow the on-screen instructions. Your credentials will be cached locally for future sessions.
2. Follow the on-screen instructions. Your credentials will be cached locally
for future sessions.
> **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.
> **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.
#### (Optional) Set your Google Cloud Project
When you log in using a Google account, you may be prompted to select a `GOOGLE_CLOUD_PROJECT`.
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.
- 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:
@@ -57,7 +72,9 @@ If you fall into one of these categories, you must:
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` :
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
@@ -68,13 +85,16 @@ export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"
```
To make this setting persistent, see [Persisting Environment Variables](#persisting-environment-variables).
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 key from Google AI Studio.
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).
1. Obtain your API key from
[Google AI Studio](https://aistudio.google.com/app/apikey).
2. Set the `GEMINI_API_KEY` environment variable:
```bash
@@ -82,13 +102,17 @@ If you don't want to authenticate using your Google account, you can use an API
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```
To make this setting persistent, see [Persisting Environment Variables](#persisting-environment-variables).
To make this setting persistent, see
[Persisting Environment Variables](#persisting-environment-variables).
> **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.
> **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
If you intend to use Google Cloud's Vertex AI platform, you have several authentication options:
If you intend to use Google Cloud's Vertex AI platform, you have several
authentication options:
- Application Default Credentials (ADC) and `gcloud`.
- A Service Account JSON key.
@@ -96,7 +120,9 @@ If you intend to use Google Cloud's Vertex AI platform, you have several authent
#### First: Set required environment variables
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`.
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:
@@ -111,7 +137,8 @@ export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
Consider this method of authentication 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:
> **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
@@ -124,35 +151,46 @@ unset GOOGLE_API_KEY GEMINI_API_KEY
gcloud auth application-default login
```
See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) for details.
See
[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 `GOOGLE_CLOUD_LOCATION` are set.
3. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and
`GOOGLE_CLOUD_LOCATION` are set.
#### 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,
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:
> **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
```
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:
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:
```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. Ensure `GOOGLE_CLOUD_PROJECT` (or `GOOGLE_CLOUD_PROJECT_ID`) and
`GOOGLE_CLOUD_LOCATION` are set.
> **Warning:** Protect your service account key file as it provides access to your resources.
> **Warning:** Protect your service account key file as it provides 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).
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
@@ -160,15 +198,24 @@ unset GOOGLE_API_KEY GEMINI_API_KEY
export GOOGLE_API_KEY="YOUR_GOOGLE_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.
> **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.
To make any of these Vertex AI environment variable settings persistent, see [Persisting Environment Variables](#persisting-environment-variables).
To make any of these Vertex AI environment variable settings persistent, see
[Persisting Environment Variables](#persisting-environment-variables).
## Persisting Environment Variables
To avoid setting environment variables in every terminal session, you can:
1. **Add your environment variables to your shell configuration file:** Append the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.profile`) and reload your shell (e.g., `source ~/.bashrc`).
1. **Add your environment variables to your shell configuration file:** Append
the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`,
`~/.zshrc`, or `~/.profile`) and reload your shell (e.g.,
`source ~/.bashrc`).
```bash
# Example for .bashrc
@@ -176,9 +223,14 @@ 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 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.
2. **Use a `.env` file:** Create a `.gemini/.env` file in your project directory or home directory. Gemini CLI automatically loads variables from the first `.env` file it finds, searching up from the current directory, then in `~/.gemini/.env` or `~/.env`. `.gemini/.env` is recommended.
2. **Use a `.env` file:** Create a `.gemini/.env` file in your project
directory or home directory. Gemini CLI automatically loads variables from
the first `.env` file it finds, searching up from the current directory,
then in `~/.gemini/.env` or `~/.env`. `.gemini/.env` is recommended.
Example for user-wide settings:
@@ -194,21 +246,28 @@ To avoid setting environment variables in every terminal session, you can:
## Non-interactive mode / headless environments
Non-interative mode / headless environments will use your existing authentication method, if an existing authentication credential is cached.
Non-interative mode / headless environments will use your existing
authentication method, if an existing authentication credential is cached.
If you have not already logged in with an authentication credential (such as a Google account), you **must** configure authentication using environment variables:
If you have not already logged in with an authentication credential (such as a
Google account), you **must** configure authentication using environment
variables:
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`.
- **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 environment variables are found.
The CLI will exit with an error in non-interactive mode if no suitable
environment variables are found.
## What's next?
Your authentication method affects your quotas, pricing, Terms of Service, and privacy notices. Review the following pages to learn more:
Your authentication method affects your quotas, pricing, Terms of Service, and
privacy notices. Review the following pages to learn more:
- [Gemini CLI: Quotas and Pricing](../quota-and-pricing.md).
- [Gemini CLI: Terms of Service and Privacy Notice](../tos-privacy.md).