Environment Variables

Gemini CLI supports configuration through environment variables, which can be set in your shell profile, system environment, or .env files.

.env File Loading

The CLI automatically loads environment variables from .env files in the following order:

Current Directory

.env file in the current working directory

Parent Directories

Searches upward in parent directories until finding an .env file, reaching a .git folder, or reaching the home directory

Home Directory

~/.env in the user’s home directory

Some environment variables (like DEBUG and DEBUG_MODE) are automatically excluded from project .env files to prevent interference. Use .gemini/.env files if you need to set these for Gemini CLI specifically.

Authentication

GEMINI_API_KEY

string

Your API key for the Gemini APIGet your key from Google AI Studio

export GEMINI_API_KEY="your-api-key-here"

GOOGLE_API_KEY

string

Your Google Cloud API key (required for Vertex AI in express mode)

export GOOGLE_API_KEY="your-google-api-key"

GOOGLE_APPLICATION_CREDENTIALS

string

Path to your Google Application Credentials JSON file

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"

# Windows PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\credentials.json"

GOOGLE_CLOUD_PROJECT

string

Your Google Cloud Project ID (required for Code Assist or Vertex AI)

export GOOGLE_CLOUD_PROJECT="your-project-id"

In Cloud Shell, this defaults to a special project for Cloud Shell users. To use a different project in Cloud Shell, define it in a .env file.

GOOGLE_CLOUD_LOCATION

string

Your Google Cloud Project Location (required for Vertex AI in non-express mode)

export GOOGLE_CLOUD_LOCATION="us-central1"

GOOGLE_GENAI_USE_VERTEXAI

boolean

Enable Vertex AI mode

export GOOGLE_GENAI_USE_VERTEXAI=true

GOOGLE_GENAI_API_VERSION

string

Specifies the API version to use for Gemini API requests

export GOOGLE_GENAI_API_VERSION="v1"

Model Configuration

GEMINI_MODEL

string

Specifies the default Gemini model to useOverrides the hardcoded default

export GEMINI_MODEL="gemini-3-flash-preview"

# Windows PowerShell
$env:GEMINI_MODEL="gemini-3-flash-preview"

CLI Behavior

GEMINI_CLI_HOME

string

Specifies the root directory for Gemini CLI’s user-level configuration and storageBy default, this is the user’s system home directory. The CLI will create a .gemini folder inside this directory.Useful for shared compute environments or keeping CLI state isolated.

export GEMINI_CLI_HOME="/path/to/user/config"

# Windows PowerShell
$env:GEMINI_CLI_HOME="C:\path\to\user\config"

GEMINI_CLI_IDE_PID

string

Manually specifies the PID of the IDE process to use for integrationUseful when running Gemini CLI in a standalone terminal while associating it with a specific IDE instance.

export GEMINI_CLI_IDE_PID="12345"

NO_COLOR

any

Set to any value to disable all color output in the CLI

export NO_COLOR=1

CLI_TITLE

string

Set to a string to customize the title of the CLI

export CLI_TITLE="My Custom Gemini"

DEBUG

boolean

Set to true or 1 to enable verbose debug logging

export DEBUG=1
gemini --debug  # Also open F12 for debug console

This variable is automatically excluded from project .env files by default.

DEBUG_MODE

boolean

Alternative to DEBUG for enabling debug mode

export DEBUG_MODE=true

Sandboxing

GEMINI_SANDBOX

boolean | string

Alternative to the sandbox setting in settings.jsonOptions: true, false, docker, podman, or a custom command string

export GEMINI_SANDBOX=docker

BUILD_SANDBOX

boolean

Automatically build the custom sandbox image from .gemini/sandbox.Dockerfile

BUILD_SANDBOX=1 gemini -s

SEATBELT_PROFILE

string

Switches the Seatbelt (sandbox-exec) profile on macOSOptions:

permissive-open (default) - Restricts writes to project folder but allows other operations
restrictive-open - Declines operations by default, allows network
strict-open - Restricts reads/writes to working directory, allows network
strict-proxied - Same as strict-open but routes network through proxy
<profile_name> - Uses custom profile from .gemini/sandbox-macos-<profile_name>.sb

export SEATBELT_PROFILE=strict-open

System Prompts

GEMINI_SYSTEM_MD

boolean | string

Replaces the built-in system prompt with content from a Markdown fileOptions:

true/1 - Use project default path ./.gemini/system.md
Any other string - Treat as a path (relative/absolute supported, ~ expands)
false/0 or unset - Use the built-in prompt

export GEMINI_SYSTEM_MD=true
# or
export GEMINI_SYSTEM_MD="/path/to/custom-system.md"

GEMINI_WRITE_SYSTEM_MD

boolean | string

Writes the current built-in system prompt to a file for reviewOptions:

true/1 - Write to ./.gemini/system.md
Otherwise treat the value as a path

Run the CLI once with this set to generate the file.

export GEMINI_WRITE_SYSTEM_MD=true
gemini

Telemetry

GEMINI_TELEMETRY_ENABLED

boolean

Set to true or 1 to enable telemetryOverrides the telemetry.enabled setting

export GEMINI_TELEMETRY_ENABLED=true

GEMINI_TELEMETRY_TARGET

string

Sets the telemetry targetOptions: local, gcpOverrides the telemetry.target setting

export GEMINI_TELEMETRY_TARGET=local

GEMINI_TELEMETRY_OTLP_ENDPOINT

string

Sets the OTLP endpoint for telemetryOverrides the telemetry.otlpEndpoint setting

export GEMINI_TELEMETRY_OTLP_ENDPOINT="http://localhost:4317"

GEMINI_TELEMETRY_OTLP_PROTOCOL

string

Sets the OTLP protocolOptions: grpc, httpOverrides the telemetry.otlpProtocol setting

export GEMINI_TELEMETRY_OTLP_PROTOCOL=grpc

GEMINI_TELEMETRY_LOG_PROMPTS

boolean

Set to true or 1 to enable logging of user promptsOverrides the telemetry.logPrompts setting

export GEMINI_TELEMETRY_LOG_PROMPTS=true

GEMINI_TELEMETRY_OUTFILE

string

Sets the file path to write telemetry to when target is localOverrides the telemetry.outfile setting

export GEMINI_TELEMETRY_OUTFILE="/path/to/telemetry.log"

GEMINI_TELEMETRY_USE_COLLECTOR

boolean

Set to true or 1 to enable using an external OTLP collectorOverrides the telemetry.useCollector setting

export GEMINI_TELEMETRY_USE_COLLECTOR=true

OTLP_GOOGLE_CLOUD_PROJECT

string

Your Google Cloud Project ID for Telemetry in Google Cloud

export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"

System Configuration

GEMINI_CLI_SYSTEM_DEFAULTS_PATH

string

Override the path to the system defaults fileDefault locations:

Linux: /etc/gemini-cli/system-defaults.json
Windows: C:\ProgramData\gemini-cli\system-defaults.json
macOS: /Library/Application Support/GeminiCli/system-defaults.json

export GEMINI_CLI_SYSTEM_DEFAULTS_PATH="/custom/path/system-defaults.json"

GEMINI_CLI_SYSTEM_SETTINGS_PATH

string

Override the path to the system settings fileDefault locations:

Linux: /etc/gemini-cli/settings.json
Windows: C:\ProgramData\gemini-cli\settings.json
macOS: /Library/Application Support/GeminiCli/settings.json

export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/custom/path/settings.json"

CODE_ASSIST_ENDPOINT

string

Specifies the endpoint for the code assist serverUseful for development and testing

export CODE_ASSIST_ENDPOINT="https://custom-endpoint.example.com"

Environment Variable Redaction

To prevent accidental leakage of sensitive information, Gemini CLI automatically redacts potential secrets from environment variables when executing tools.

Default Redaction Rules

By Name

Variables are redacted if their names contain:

TOKEN
SECRET
PASSWORD
KEY
AUTH
CREDENTIAL
PRIVATE
CERT

By Value Pattern

Variables are redacted if their values match:

Private keys (RSA, OpenSSH, PGP, etc.)
Certificates
URLs containing credentials
API keys and tokens (GitHub, Google, AWS, Stripe, Slack, etc.)

Specific Blocklist

These variables are always redacted by default:

CLIENT_ID
DB_URI
DATABASE_URL
CONNECTION_STRING

Never Redacted (Allowlist)

Common system variables: PATH, HOME, USER, SHELL, TERM, LANG
Variables starting with GEMINI_CLI_
GitHub Action specific variables

Custom Redaction Configuration

Configure redaction behavior in your settings.json:

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
      "blocked": ["INTERNAL_IP_ADDRESS", "CUSTOM_SENSITIVE_VAR"]
    }
  }
}

security.environmentVariableRedaction.enabled

boolean

default:"false"

Enable redaction of environment variables that may contain secrets

security.environmentVariableRedaction.allowed

array

default:"[]"

Environment variables to always allow (bypass redaction)

security.environmentVariableRedaction.blocked

array

default:"[]"

Environment variables to always redact

Example Configurations

Basic Setup with API Key

# ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-flash"

Vertex AI Configuration

# Project .env file
GOOGLE_API_KEY="your-google-api-key"
GOOGLE_CLOUD_PROJECT="my-project-id"
GOOGLE_CLOUD_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=true

Development Setup with Debug

# .gemini/.env (not excluded like project .env)
DEBUG=1
DEBUG_MODE=true
GEMINI_TELEMETRY_ENABLED=true
GEMINI_TELEMETRY_TARGET=local
GEMINI_TELEMETRY_OUTFILE="./telemetry.log"

Sandboxed Environment

export GEMINI_SANDBOX=docker
export BUILD_SANDBOX=1
export SEATBELT_PROFILE=strict-open  # macOS only

Custom Home Directory (Shared Computing)

export GEMINI_CLI_HOME="/workspace/users/$USER/.gemini-config"
export GEMINI_MODEL="gemini-3-flash-preview"

Shell Profile Examples

Bash (~/.bashrc)

# Gemini CLI Configuration
export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="gemini-2.5-pro"
export GEMINI_CLI_HOME="$HOME/.config/gemini"

# Optional: Add alias for quick access
alias gm="gemini"
alias gms="gemini --sandbox"

Zsh (~/.zshrc)

# Gemini CLI Configuration
export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="gemini-2.5-flash"

# Load project-specific .env if available
if [[ -f .env ]]; then
  export $(cat .env | xargs)
fi

PowerShell (Windows)

# Microsoft.PowerShell_profile.ps1
$env:GEMINI_API_KEY="your-api-key"
$env:GEMINI_MODEL="gemini-2.5-pro"
$env:GEMINI_CLI_HOME="$HOME\.config\gemini"

# Optional: Add alias
Set-Alias gm gemini

Settings Reference

Configure Gemini CLI with settings.json

Authentication

Complete authentication setup guide

Sandboxing

Safe execution environments

Telemetry

Usage tracking and monitoring

Command Reference

Configuration

Development

Environment Variables

.env File Loading

Authentication

Model Configuration

CLI Behavior

Sandboxing

System Prompts

Telemetry

System Configuration

Environment Variable Redaction

Default Redaction Rules

Never Redacted (Allowlist)

Custom Redaction Configuration

Example Configurations

Basic Setup with API Key

Vertex AI Configuration

Development Setup with Debug

Sandboxed Environment

Custom Home Directory (Shared Computing)

Shell Profile Examples

Bash (~/.bashrc)

Zsh (~/.zshrc)

PowerShell (Windows)

Settings Reference

Authentication

Sandboxing

Telemetry

Build docs developers (and LLMs) love

Command Reference

Configuration

Development

​.env File Loading

​Authentication

​Model Configuration

​CLI Behavior

​Sandboxing

​System Prompts

​Telemetry

​System Configuration

​Environment Variable Redaction

​Default Redaction Rules

​Never Redacted (Allowlist)

​Custom Redaction Configuration

​Example Configurations

​Basic Setup with API Key

​Vertex AI Configuration

​Development Setup with Debug

​Sandboxed Environment

​Custom Home Directory (Shared Computing)

​Shell Profile Examples

​Bash (~/.bashrc)

​Zsh (~/.zshrc)

​PowerShell (Windows)

​Related Resources

Settings Reference

Authentication

Sandboxing

Telemetry

Build docs developers (and LLMs) love

.env File Loading

Authentication

Model Configuration

CLI Behavior

Sandboxing

System Prompts

Telemetry

System Configuration

Environment Variable Redaction

Default Redaction Rules

Never Redacted (Allowlist)

Custom Redaction Configuration

Example Configurations

Basic Setup with API Key

Vertex AI Configuration

Development Setup with Debug

Sandboxed Environment

Custom Home Directory (Shared Computing)

Shell Profile Examples

Bash (~/.bashrc)

Zsh (~/.zshrc)

PowerShell (Windows)

Related Resources