Gemini CLI requires authentication using Google’s services. Before using Gemini CLI, configure one of the following authentication methods:
If you are running the Gemini CLI within a Google Cloud Shell environment, authentication is typically automatic using your Cloud Shell credentials.
When you run Gemini CLI through the command-line, Gemini CLI will provide the following options:
> 1. Login with Google
> 2. Use Gemini API key
> 3. Vertex AI
The following sections provide instructions for each of these authentication options.
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.
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.
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
localhostURL that the CLI listens on during setup.
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:
If you fall into one of these categories, you must:
To set the project ID, export the GOOGLE_CLOUD_PROJECT environment variable:
# 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.
If you don’t want to authenticate using your Google account, you can use an API key from Google AI Studio.
Set the GEMINI_API_KEY environment variable:
# 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.
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.
If you intend to use Google Cloud’s Vertex AI platform, you have several authentication options:
gcloud.Regardless of your method of authentication, you’ll typically need to set the following variables: GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.
To set these variables:
# Replace with your project ID and desired location (e.g., us-central1)
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
gcloudConsider this method of authentication if you have Google Cloud CLI installed.
Note: If you have previously set
GOOGLE_API_KEYorGEMINI_API_KEY, you must unset them to use ADC:
unset GOOGLE_API_KEY GEMINI_API_KEY
Log in to Google Cloud:
gcloud auth application-default login
See Set up Application Default Credentials for details.
GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION are set.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_KEYorGEMINI_API_KEY, you must unset them:
unset GOOGLE_API_KEY GEMINI_API_KEY
Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the JSON file’s absolute path:
# Replace /path/to/your/keyfile.json with the actual path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION are set.Warning: Protect your service account key file as it provides access to your resources.
Set the GOOGLE_API_KEY environment variable:
# Replace YOUR_GOOGLE_API_KEY with your Vertex AI 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 or ADC methods instead.
To make any of these Vertex AI environment variable settings persistent, see Persisting Environment Variables.
To avoid setting environment variables in every terminal session, you can:
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).
# Example for .bashrc
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
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.
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:
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
# Add other variables like GEMINI_API_KEY as needed
EOF
Variables are loaded from the first file found, not merged.
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:
GEMINI_API_KEY.GOOGLE_GENAI_USE_VERTEXAI=true.GOOGLE_API_KEY.GOOGLE_APPLICATION_CREDENTIALS) and set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.The CLI will exit with an error in non-interactive mode if no suitable environment variables are found.
Your authentication method affects your quotas, pricing, Terms of Service, and privacy notices. Review the following pages to learn more: