Authentication Setup

LLxprt Code supports multiple authentication methods for various AI providers. For Google's AI services, 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, LLxprt Code 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 LLxprt Code is being run from. (Specifically, the browser will be redirected to a localhost url that LLxprt Code will be listening on).
- Users may have to specify a GOOGLE_CLOUD_PROJECT if:
  1. 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. your-name@your-company.com), enhanced security features, and administrative controls. These accounts are often managed by an employer or school.
  2. You have received a Gemini Code Assist license through the Google Developer Program (including qualified Google Developer Experts)
  3. You have been assigned a license to a current Gemini Code Assist standard or enterprise subscription.
  4. You are using the product outside the supported regions for free individual usage.
  5. 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:
```
export 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:
```
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc
```
Gemini API key:
- 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, replace YOUR_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:
```
export 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:
```
echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
source ~/.bashrc
```
    :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.
Vertex AI:
- API Key:
  - Obtain your Google Cloud API key: Get an API Key
  - Set the GOOGLE_API_KEY environment variable. In the following methods, replace YOUR_GOOGLE_API_KEY with your Vertex AI API key:
    - You can temporarily set the environment variable in your current shell session using the following command:
```
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
```
    - 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:
```
echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc
source ~/.bashrc
```
      :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.
      
      Note: If you encounter an error like "API keys are not supported by this API - Expected OAuth2 access token or other authentication credentials that assert a principal", it is likely that your organization has restricted the creation of service account API keys. In this case, please try the service account JSON key method described below.
- Application Default Credentials (ADC):
  Note: If you have previously set the GOOGLE_API_KEY or GEMINI_API_KEY environment variables, you must unset them to use Application Default Credentials.
```
unset GOOGLE_API_KEY GEMINI_API_KEY
```
  - Using gcloud (for local development):
    - Ensure you have a Google Cloud project and have enabled the Vertex AI API.
    - Log in with your user credentials:
```
gcloud auth application-default login
```
      For more information, see Set up Application Default Credentials for Google Cloud.
  - Using a Service Account (for applications or when service account API keys are restricted):
    - If you are unable to create an API key due to organization policies, or if you are running in a non-interactive environment, you can authenticate using a service account key.
    - Create a service account and key, and download the JSON key file. The service account will need to be assigned the "Vertex AI User" role.
    - Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the absolute path of the JSON file.
      - You can temporarily set the environment variable in your current shell session:
        export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
      - For repeated use, you can add the command to your shell's configuration file (e.g., ~/.bashrc).
        echo 'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"' >> ~/.bashrc source ~/.bashrc
        :warning: Be advised that when you export service account credentials inside your shell configuration file, any other process executed from the shell can read it.
  - Required Environment Variables for ADC:
    - When using ADC (either with gcloud or a service account), you must also set the GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION environment variables. In the following methods, replace YOUR_PROJECT_ID and YOUR_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:
        export 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 or your shell's configuration file (like ~/.bashrc, ~/.zshrc, or ~/.profile). For example, the following commands add the environment variables to a ~/.bashrc file:
        echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc source ~/.bashrc
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 llxprt-code behavior. Use .llxprt/.env files for llxprt-code specific variables.

LLxprt Code 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:
1. .gemini/.env
2. .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 LLxprt Code 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.
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 and GOOGLE_CLOUD_LOCATION environment variables are set.

If none of these environment variables are set in a non-interactive session, the CLI will exit with an error.

Multi-Provider Authentication

LLxprt Code supports authentication with multiple AI providers beyond Google. Use the /auth command to manage OAuth authentication for providers that support it:

Anthropic - OAuth for Claude models
Gemini - OAuth for Google AI
Codex - OAuth for ChatGPT Plus/Pro subscribers (use /auth codex for OAuth; access GPT-5 without API keys)
Qwen - OAuth for Alibaba Cloud models

The `/auth` Command

/auth <provider> <action> [bucket-name]

Providers: anthropic, gemini, codex (OpenAI), qwen, and others

Actions:

login [bucket] - Authenticate with the provider (optionally to a named bucket)
logout [bucket|--all] - Remove authentication
status - Show all authenticated buckets and their status
switch <bucket> - Switch to a different bucket

OAuth Buckets

OAuth buckets let you manage multiple authentication contexts per provider. This is useful when you have multiple accounts or API credentials for the same provider.

Creating buckets:

# Default bucket (no name)
/auth anthropic login

# Named buckets
/auth anthropic login work@company.com
/auth anthropic login personal@gmail.com

# OpenAI OAuth for ChatGPT Plus/Pro subscribers
/auth codex login

Viewing buckets:

/auth anthropic status

Shows all buckets with their authentication status and token expiry.

Switching buckets:

/auth anthropic switch work@company.com

Logging out:

# Logout from specific bucket
/auth anthropic logout work@company.com

# Logout from all buckets
/auth anthropic logout --all

Using Buckets with Profiles

Buckets are most powerful when combined with profiles. You can save a profile that uses specific buckets:

# Single bucket
/profile save model work-profile work@company.com

# Multiple buckets (automatic failover on rate limits)
/profile save model ha-profile bucket1 bucket2 bucket3

When a profile has multiple buckets, LLxprt Code automatically fails over to the next bucket when encountering rate limits (429) or quota errors (402).

For more details, see Profiles.

Viewing Bucket Statistics

/stats buckets

Shows request counts and last-used timestamps for all OAuth buckets across providers.

API Key Authentication

For providers that use API keys instead of OAuth, you can use environment variables or the /key and /keyfile commands:

Environment variables:

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"

In-session commands:

/key <api-key>
/keyfile /path/to/keyfile

These commands set the API key for the current provider. The key is not persisted between sessions unless saved in a profile.

Authentication Priority

When multiple authentication methods are available, LLxprt Code uses this priority:

CLI flags (--key, --keyfile)
Profile settings (if a profile is loaded)
OAuth tokens (from /auth login)
Environment variables