Skip to main content

​
Overview

To use Gemini CLI, you need to authenticate with Google. This guide helps you choose the best authentication method based on your account type and use case.
Quick Start: Most users should start with Login with Google for the simplest setup.

​
Choose Your Authentication Method

Select the method that matches your situation:
User Type / ScenarioRecommended MethodGoogle Cloud Project Required
Individual Google accountsLogin with GoogleNo, with exceptions
Organization users (company, school, Workspace)Login with GoogleYes
AI Studio user with Gemini API keyUse Gemini API KeyNo
Google Cloud Vertex AI userVertex AIYes
Headless/non-interactive modeAPI Key or Vertex AIDepends on method

​
Account Types Explained

Individual Google accounts include:
  • Free tier accounts (Gemini Code Assist for individuals)
  • Paid subscriptions (Google AI Pro and Ultra)
  • Personal Gmail accounts
Free tier benefits:
  • 60 requests/min
  • 1,000 requests/day

​
Login with Google

The simplest authentication method for local development. Requires a web browser that can communicate with your terminal.
1

Start Gemini CLI

gemini
2

Select Login with Google

When prompted “How would you like to authenticate for this project?”, select Login with Google.Gemini CLI will open a login prompt in your web browser.
3

Follow Authentication Flow

Follow the on-screen instructions in your browser to sign in with your Google account.Your credentials will be cached locally for future sessions.
Google AI Pro/Ultra subscribers: Use the Google account associated with your subscription.

​
Do I Need a Google Cloud Project?

Most individual accounts don’t require a Google Cloud project. However, you’ll need one if:
  • You’re using a company, school, or Google Workspace account
  • You have a Gemini Code Assist license from the Google Developer Program
  • You have a Gemini Code Assist subscription
If you need to set a Google Cloud project, see Set Your Google Cloud Project.

​
Gemini API Key

Use an API key from Google AI Studio if you prefer not to authenticate with your Google account directly.
1

Obtain API Key

Get your API key from Google AI Studio.
2

Set Environment Variable

# Replace YOUR_GEMINI_API_KEY with your actual key
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
To make this persistent, see Persisting Environment Variables.
3

Start Gemini CLI

gemini
Select Use Gemini API key when prompted.
Treat API keys as sensitive credentials. Protect them to prevent unauthorized access and potential misuse of the service under your account.

​
API Key Benefits

  • Free tier: 1000 requests/day with Gemini 3 (mix of flash and pro)
  • Model selection: Choose specific Gemini models
  • Usage-based billing: Upgrade for higher limits when needed

​
Vertex AI

For enterprise teams and production workloads using Google Cloud’s Vertex AI platform.
All Vertex AI authentication methods require setting GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.

​
Prerequisites

Set required environment variables for all Vertex AI methods: 
# 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"

​
Method A: Application Default Credentials (ADC)

Best if you have Google Cloud CLI installed.
1

Unset Conflicting Variables

If you previously set GOOGLE_API_KEY or GEMINI_API_KEY, unset them:
unset GOOGLE_API_KEY GEMINI_API_KEY
2

Verify Google Cloud Setup

Ensure you have a Google Cloud project with Vertex AI API enabled.
3

Login to Google Cloud

gcloud auth application-default login
4

Configure Project

See Set Your Google Cloud Project.
5

Start Gemini CLI

gemini
Select Vertex AI when prompted.

​
Method B: Service Account JSON Key

Ideal for non-interactive environments, CI/CD pipelines, or restricted environments.
1

Unset Conflicting Variables

unset GOOGLE_API_KEY GEMINI_API_KEY
2

Create Service Account

Create a service account and key and download the JSON file.Assign the Vertex AI User role to the service account.
3

Set Credentials Path

# Replace /path/to/your/keyfile.json with the actual path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
4

Configure Project

See Set Your Google Cloud Project.
5

Start Gemini CLI

gemini
Select Vertex AI when prompted.
Protect your service account key file as it provides access to your Google Cloud resources.

​
Method C: Google Cloud API Key

1

Obtain API Key

Get an API Key from Google Cloud.
2

Set Environment Variable

# Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
3

Configure Project

See Set Your Google Cloud Project.
4

Start Gemini CLI

gemini
Select Vertex AI when prompted.
If you see errors like “API keys are not supported by this API…”, your organization might restrict API key usage. Try other Vertex AI authentication methods instead.

​
Set Google Cloud Project

Required for organization accounts and Vertex AI authentication.
Most individual Google accounts (free and paid) don’t require a Google Cloud project.
1

Find Your Project ID

Find your Google Cloud Project ID in the Google Cloud Console.
2

Enable Gemini API

Enable the Gemini for Cloud API for your project.
3

Configure IAM Access

Configure necessary IAM access permissions for your user or service account.
4

Set Environment Variable

# Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
To make this persistent, see Persisting Environment Variables.
Gemini CLI checks for GOOGLE_CLOUD_PROJECT first, then falls back to GOOGLE_CLOUD_PROJECT_ID.

​
Persisting Environment Variables

Avoid setting environment variables for every terminal session by persisting them:

​
Method 1: Shell Configuration File

Add environment variables to your shell’s startup file: 
# Add to your shell config file
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
echo 'export GEMINI_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
Any process launched from your shell can read environment variables exported in your shell configuration file.
Create a .gemini/.env file in your project or home directory. Gemini CLI automatically loads variables from the first .env file it finds. 
# Create user-wide settings
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
GEMINI_API_KEY="your-api-key"
# Add other variables as needed
EOF
Gemini CLI searches for .env files starting from the current directory, then up the directory tree, and finally in ~/.gemini/.env.

​
Google Cloud Environments

When running Gemini CLI in certain Google Cloud environments, authentication is automatic:

Cloud Shell

Gemini CLI automatically authenticates using your Cloud Shell credentials.

Compute Engine

Gemini CLI automatically uses Application Default Credentials (ADC) from the environment’s metadata server.
If automatic authentication fails, use one of the interactive methods described above.

​
Headless Mode

For headless/non-interactive mode, Gemini CLI uses your existing authentication if credentials are cached. If you haven’t logged in yet, you must configure authentication using environment variables:

​
Troubleshooting

  • Verify your credentials are correct
  • Check that required environment variables are set
  • Ensure you’ve selected the correct authentication method
  • Try clearing cached credentials and re-authenticating
  • Verify the project ID is correct
  • Ensure the Gemini for Cloud API is enabled
  • Check that your account has the necessary IAM permissions
  • Confirm GOOGLE_CLOUD_PROJECT is set correctly
  • Verify the API key is copied correctly (no extra spaces)
  • Check that the API key hasn’t expired or been revoked
  • Ensure you’re using the correct API key for your chosen method (Gemini API vs Vertex AI)
  • For Vertex AI API keys, verify your organization allows API key usage
  • Ensure the service account has the “Vertex AI User” role
  • Verify the JSON key file path is correct
  • Check that the key file is readable by your user
  • Confirm GOOGLE_APPLICATION_CREDENTIALS points to a valid JSON file

​
Next Steps

Quick Start Guide

Get to your first working command in minutes

Quotas and Pricing

Learn about quotas, pricing, and terms of service

Build docs developers (and LLMs) love

Get started for freeTalk to us