Gemini CLI reference - Environment variables
Gemini CLI environment variables
Gemini CLI documents 33 environment variables, including GEMINI_API_KEY, GEMINI_MODEL and GEMINI_CLI_TRUST_WORKSPACE. Gemini CLI reads these from your shell environment. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 6 official pagesFull Gemini CLI reference
| Variable | Description | Example |
|---|---|---|
GEMINI_API_KEY | Your API key for the Gemini API. Docs: GEMINI_API_KEY | -no example |
GEMINI_MODEL | Specifies the default Gemini model, overriding the hardcoded default. Docs: GEMINI_MODEL | export GEMINI_MODEL="gemini-3-flash-preview" |
GEMINI_CLI_TRUST_WORKSPACE | If "true", trusts the current workspace for the session, bypassing the folder trust check. "true" Docs: GEMINI_CLI_TRUST_WORKSPACE | -no example |
GEMINI_CLI_TRUSTED_FOLDERS_PATH | Overrides the default location of trustedFolders.json. path Docs: GEMINI_CLI_TRUSTED_FOLDERS_PATH | -no example |
GEMINI_CLI_IDE_PID | Manually specifies the IDE process PID for integration, overriding auto-detection. PID Docs: GEMINI_CLI_IDE_PID | -no example |
GEMINI_CLI_HOME | Root directory for user-level configuration and storage; a .gemini folder is created inside it. path; default: user home Docs: GEMINI_CLI_HOME | export GEMINI_CLI_HOME="/path/to/user/config" |
GEMINI_CLI_SURFACE | Custom label included in the User-Agent header for API traffic reporting. string Docs: GEMINI_CLI_SURFACE | export GEMINI_CLI_SURFACE="my-custom-tool" |
GEMINI_CLI_SYSTEM_DEFAULTS_PATH | Overrides the path of the system defaults settings file. path Docs: GEMINI_CLI_SYSTEM_DEFAULTS_PATH | -no example |
GEMINI_CLI_SYSTEM_SETTINGS_PATH | Overrides the path of the system settings (override) file. path Docs: GEMINI_CLI_SYSTEM_SETTINGS_PATH | -no example |
GOOGLE_API_KEY | Google Cloud API key; required for Vertex AI express mode. Docs: GOOGLE_API_KEY | export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" |
GOOGLE_CLOUD_PROJECT | Google Cloud Project ID; required for Code Assist or Vertex AI. Docs: GOOGLE_CLOUD_PROJECT | export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" |
GOOGLE_CLOUD_LOCATION | Google Cloud location (for example us-central1); required for Vertex AI non-express mode. Docs: GOOGLE_CLOUD_LOCATION | export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" |
GOOGLE_APPLICATION_CREDENTIALS | Path to your Google Application Credentials JSON file. string (path) Docs: GOOGLE_APPLICATION_CREDENTIALS | export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json" |
GOOGLE_GENAI_API_VERSION | API version for Gemini API requests, overriding the SDK default. Docs: GOOGLE_GENAI_API_VERSION | export GOOGLE_GENAI_API_VERSION="v1" |
GOOGLE_GEMINI_BASE_URL | Overrides the Gemini API base URL (gemini-api-key auth); must be HTTPS unless localhost. URL Docs: GOOGLE_GEMINI_BASE_URL | export GOOGLE_GEMINI_BASE_URL="https://my-proxy.com" |
GOOGLE_VERTEX_BASE_URL | Overrides the Vertex AI base URL (vertex-ai auth); must be HTTPS unless localhost. URL Docs: GOOGLE_VERTEX_BASE_URL | export GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com" |
OTLP_GOOGLE_CLOUD_PROJECT | Google Cloud Project ID for telemetry in Google Cloud. Docs: OTLP_GOOGLE_CLOUD_PROJECT | export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" |
GEMINI_TELEMETRY_ENABLED | true or 1 enables telemetry; overrides telemetry.enabled. Related overrides: GEMINI_TELEMETRY_TRACES_ENABLED, _TARGET, _OTLP_ENDPOINT, _OTLP_PROTOCOL, _OTLP_HEADERS, _LOG_PROMPTS, _OUTFILE, _USE_COLLECTOR, _USE_CLI_AUTH. true/1 Docs: GEMINI_TELEMETRY_ENABLED | -no example |
GEMINI_SANDBOX | Alternative to the sandbox setting; enables sandboxing. true, false, docker, podman, sandbox-exec, runsc, lxc, or a custom command Docs: GEMINI_SANDBOX | export GEMINI_SANDBOX=docker |
GEMINI_SANDBOX_IMAGE | Custom container image to use for sandboxing. image name Docs: GEMINI_SANDBOX_IMAGE | export GEMINI_SANDBOX_IMAGE="us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest" |
BUILD_SANDBOX | Builds a custom sandbox image from .gemini/sandbox.Dockerfile. 1 Docs: BUILD_SANDBOX | BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build" |
SANDBOX_MOUNTS | Comma-separated from:to:opts mounts giving the sandbox access outside the workspace; opts defaults to ro. from:to:opts list Docs: SANDBOX_MOUNTS | export SANDBOX_MOUNTS="/path/on/host:/path/in/container:rw,/another/path:ro" |
SANDBOX_FLAGS | Custom flags injected into the docker or podman command. string Docs: SANDBOX_FLAGS | export SANDBOX_FLAGS="--security-opt label=disable" |
SEATBELT_PROFILE | Switches the macOS Seatbelt (sandbox-exec) profile. permissive-open (default), permissive-proxied, restrictive-open, restrictive-proxied, strict-open, strict-proxied, or a custom <profile_name> Docs: SEATBELT_PROFILE | -no example |
GEMINI_SYSTEM_MD | Replaces the built-in system prompt with a Markdown file; true/1 uses ./.gemini/system.md, other strings are paths. true/1, false/0, or a path Docs: GEMINI_SYSTEM_MD | -no example |
GEMINI_WRITE_SYSTEM_MD | Writes the built-in system prompt to a file for review; true/1 writes ./.gemini/system.md. true/1 or a path Docs: GEMINI_WRITE_SYSTEM_MD | -no example |
DEBUG / DEBUG_MODE | true or 1 enables verbose debug logging; excluded from project .env files by default. true/1 Docs: DEBUG / DEBUG_MODE | -no example |
NO_COLOR | Set to any value to disable all color output. any value Docs: NO_COLOR | -no example |
CLI_TITLE | Customizes the title of the CLI. string Docs: CLI_TITLE | -no example |
CODE_ASSIST_ENDPOINT | Endpoint for the code assist server, for development and testing. URL Docs: CODE_ASSIST_ENDPOINT | -no example |
GEMINI_CLI | Set to 1 in subprocesses run via ! or shell mode so scripts can detect Gemini CLI. 1 Docs: GEMINI_CLI | -no example |
GEMINI_PROJECT_DIR | Hook environment: absolute path to the project root. Hooks also get GEMINI_PLANS_DIR, GEMINI_SESSION_ID, GEMINI_CWD and CLAUDE_PROJECT_DIR (alias). Docs: GEMINI_PROJECT_DIR | -no example |
NODE_USE_SYSTEM_CA | Set to 1 to make Node.js use the system certificate store (corporate TLS fix); alternative is NODE_EXTRA_CA_CERTS. 1 Docs: NODE_USE_SYSTEM_CA | export NODE_USE_SYSTEM_CA=1 |
The rest of the Gemini CLI reference
FAQ
How many environment variables does Gemini CLI have?
The official Gemini CLI docs list 33 environment variables, including GEMINI_API_KEY, GEMINI_MODEL and GEMINI_CLI_TRUST_WORKSPACE. All of them are in the table above, in the docs' order.
What does GEMINI_API_KEY do in Gemini CLI?
Your API key for the Gemini API.
Where are Gemini CLI environment variables documented?
On 6 official docs pages at github.com, last read on October 17, 2026. Every row in the table links the exact section it came from.
More on Gemini CLI
Sources
Last verified . Names and examples are copied verbatim from the 6 official pages below, and every row above links the exact section it came from.
- github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md23 items
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/telemetry.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md6 items
- github.com/google-gemini/gemini-cli/blob/main/docs/reference/commands.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/resources/troubleshooting.md1 item
Newsletter
Know when your tools change
One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.