Authentication Setup
The Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure one of the following authentication methods:
Login with Google (Gemini Code Assist):
Use this option to log in with your google account.
During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs.
Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on).
Users may have to specify a GOOGLE_CLOUD_PROJECT if:
- You have a Google Workspace account. Google Workspace is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. [email protected]), enhanced security features, and administrative controls. These accounts are often managed by an employer or school.
- You have received a Gemini Code Assist license through the Google Developer Program (including qualified Google Developer Experts)
- You have been assigned a license to a current Gemini Code Assist standard or enterprise subscription.
- You are using the product outside the supported regions for free individual usage.
- You are a Google account holder under the age of 18
- If you fall into one of these categories, you must first configure a Google Cloud Project ID to use, enable the Gemini for Cloud API and configure access permissions.
You can temporarily set the environment variable in your current shell session using the following command:
bashexport GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
- For repeated use, you can add the environment variable to your .env file or your shell's configuration file (like
~/.bashrc
,~/.zshrc
, or~/.profile
). For example, the following command adds the environment variable to a~/.bashrc
file:
bashecho 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc source ~/.bashrc
- Obtain your API key from Google AI Studio: https://aistudio.google.com/app/apikey
- Set the
GEMINI_API_KEY
environment variable. In the following methods, replaceYOUR_GEMINI_API_KEY
with the API key you obtained from Google AI Studio:You can temporarily set the environment variable in your current shell session using the following command:
bashexport GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
For repeated use, you can add the environment variable to your .env file.
Alternatively you can export the API key from your shell's configuration file (like
~/.bashrc
,~/.zshrc
, or~/.profile
). For example, the following command adds the environment variable to a~/.bashrc
file:bashecho 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc source ~/.bashrc
⚠️ Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
Vertex AI:
- Obtain your Google Cloud API key: Get an API Key
- Set the
GOOGLE_API_KEY
environment variable. In the following methods, replaceYOUR_GOOGLE_API_KEY
with your Vertex AI API key:- You can temporarily set these environment variables in your current shell session using the following commands:bash
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
- For repeated use, you can add the environment variables to your .env file or your shell's configuration file (like
~/.bashrc
,~/.zshrc
, or~/.profile
). For example, the following commands add the environment variables to a~/.bashrc
file:bashecho 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc source ~/.bashrc
- You can temporarily set these environment variables in your current shell session using the following commands:
- Set the
- To use Application Default Credentials (ADC), use the following command:
- Ensure you have a Google Cloud project and have enabled the Vertex AI API.bashFor more information, see Set up Application Default Credentials for Google Cloud.
gcloud auth application-default login
- Set the
GOOGLE_CLOUD_PROJECT
andGOOGLE_CLOUD_LOCATION
environment variables. In the following methods, replaceYOUR_PROJECT_ID
andYOUR_PROJECT_LOCATION
with the relevant values for your project:You can temporarily set these environment variables in your current shell session using the following commands:
bashexport GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1
For repeated use, you can add the environment variables to your .env file
Alternatively you can export the environment variables from your shell's configuration file (like
~/.bashrc
,~/.zshrc
, or~/.profile
). For example, the following commands add the environment variables to a~/.bashrc
file:bashecho 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc source ~/.bashrc
⚠️ Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
- Ensure you have a Google Cloud project and have enabled the Vertex AI API.
- Obtain your Google Cloud API key: Get an API Key
Cloud Shell:
This option is only available when running in a Google Cloud Shell environment.
It automatically uses the credentials of the logged-in user in the Cloud Shell environment.
This is the default authentication method when running in Cloud Shell and no other method is configured.
:warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
Persisting Environment Variables with .env
Files
You can create a .gemini/.env
file in your project directory or in your home directory. Creating a plain .env
file also works, but .gemini/.env
is recommended to keep Gemini variables isolated from other tools.
Important: Some environment variables (like DEBUG
and DEBUG_MODE
) are automatically excluded from project .env
files to prevent interference with gemini-cli behavior. Use .gemini/.env
files for gemini-cli specific variables.
Gemini CLI automatically loads environment variables from the first .env
file it finds, using the following search order:
- Starting in the current directory and moving upward toward
/
, for each directory it checks:.gemini/.env
.env
- If no file is found, it falls back to your home directory:
~/.gemini/.env
~/.env
Important: The search stops at the first file encountered—variables are not merged across multiple files.
Examples
Project-specific overrides (take precedence when you are inside the project):
mkdir -p .gemini
echo 'GOOGLE_CLOUD_PROJECT="your-project-id"' >> .gemini/.env
User-wide settings (available in every directory):
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
GEMINI_API_KEY="your-gemini-api-key"
EOF
Non-Interactive Mode / Headless Environments
When running the Gemini CLI in a non-interactive environment, you cannot use the interactive login flow. Instead, you must configure authentication using environment variables.
The CLI will automatically detect if it is running in a non-interactive terminal and will use one of the following authentication methods if available:
Gemini API Key:
- Set the
GEMINI_API_KEY
environment variable. - The CLI will use this key to authenticate with the Gemini API.
- Set the
Vertex AI:
- Set the
GOOGLE_GENAI_USE_VERTEXAI=true
environment variable. - Using an API Key: Set the
GOOGLE_API_KEY
environment variable. - Using Application Default Credentials (ADC):
- Run
gcloud auth application-default login
in your environment to configure ADC. - Ensure the
GOOGLE_CLOUD_PROJECT
andGOOGLE_CLOUD_LOCATION
environment variables are set.
- Run
- Set the
If none of these environment variables are set in a non-interactive session, the CLI will exit with an error.