What auth options can I use with Gemini CLI

OAuth Login (Google Account)
The primary and recommended authentication method for most individual developers is OAuth login using a personal Google Account. When a user first runs the Gemini CLI, they are prompted to authenticate by signing in with their Google credentials through a web-based OAuth flow. This grants the user a free Gemini Code Assist license with access to Gemini 2.5 Pro features, such as a 1 million token context window. The OAuth authentication process is user-friendly, designed to facilitate quick onboarding, and does not require manual API key management. It also provides a free tier with limits of 60 model requests per minute and 1,000 requests per day without any charge. This method is particularly suitable for individual developers and those using the CLI in personal or exploratory contexts.

API Key Authentication
For developers who require more control over their usage, higher rate limits, or want to work in environments where OAuth login is not practical (such as headless servers or CI/CD pipelines), the Gemini CLI supports authentication via an API key. This API key is generated from Google AI Studio or relevant Google Cloud environments. Users need to set the API key as an environment variable in their terminal session using:

export GEMINI_API_KEY="YOUR_API_KEY"

This method is favored by professional developers and organizations that want to manage billing based on usage or automate their interactions with Gemini in scripted or automated workflows. API key authentication allows for a more flexible and scalable approach but requires users to responsibly manage and secure their keys to prevent unauthorized access.

Vertex AI Authentication
Another authentication option is through Google Cloud Vertex AI. This method is intended for enterprise users and developers who are leveraging Google Cloud's Vertex AI infrastructure for AI workloads. To authenticate with Vertex AI, users must set the appropriate environment variables:

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true

This method integrates Gemini CLI usage with Google Cloud's identity and access management systems, enabling usage-based billing, enhanced security policies, and enterprise-level control over API access. It suits organizations with existing Google Cloud deployments who want to incorporate Gemini AI capabilities within their cloud infrastructure.

Behavior with API Key in Environment Files
A notable behavior of Gemini CLI is that if a `.env` file containing the `GEMINI_API_KEY` environment variable is detected in the current directory when launching the CLI, it automatically uses that key to authenticate and bypasses the typical OAuth-based onboarding. While this feature offers convenience, it can cause confusion as the user might not be presented with an option to select other authentication methods. There is ongoing discussion in the community and GitHub issues about improving this interaction to better handle multiple authentication contexts.

Headless Server Authentication
Authenticating Gemini CLI on a headless server or remote environment without browser access can be challenging. Some community-suggested approaches include the CLI outputting the authentication URL to a temporary file, which users can copy and open in a browser on a different machine to complete Google OAuth login. After successful login, the redirected localhost URL that doesn't function on the headless server can be manually handled using tools like wget or SSH port forwarding to complete the authentication handshake. This workaround is necessary because the CLI primarily relies on interactive OAuth login via browser but also supports API key usage which is simpler in headless environments.

Persistence and Settings File
Once authentication is done, Gemini CLI saves the selected authentication method and related settings in a configuration file called `settings.json`. This file typically resides in platform-specific locations such as:

- Linux/macOS: `~/.gemini/settings.json`
- Windows: `%USERPROFILE%\.gemini\settings.json`
- System-wide (Linux): `/etc/gemini-cli/settings.json`
- System-wide (Windows): `%ProgramData%\gemini-cli\settings.json`

This persistence means subsequent runs of the CLI do not require re-authentication unless credentials are revoked or changed. The settings file also allows customization of themes and other CLI parameters aside from authentication.

Enterprise and Google Workspace Authentication
In addition to the above, enterprise users, including those with Google Workspace accounts, may have additional authentication pathways and licensing options for broader or higher-tier access. These methods are documented more specifically in enterprise-focused guides and may involve specialized Cloud Identity configurations or domain-wide delegation.

Summary of Available Authentication Options for Gemini CLI:
- OAuth login with personal Google Account (recommended for most users, free tier access)
- API Key authentication by setting `GEMINI_API_KEY` environment variable (for automated or professional use)
- Vertex AI authentication using Google Cloud environment variables (for enterprise and cloud integration)
- Special handling for `.env` files containing API keys that automate authentication
- Workarounds for headless or remote server login through URL copy-paste or API keys
- Configuration persistence via `settings.json` for seamless repeated use

This system provides flexibility to accommodate individual developers, enterprises, automated workflows, and cloud-based deployments while balancing ease of use, control, and security. Users should select the authentication method that best fits their environment and usage scenario.