diff options
| -rw-r--r-- | docs/cli/authentication.md | 42 |
1 files changed, 38 insertions, 4 deletions
diff --git a/docs/cli/authentication.md b/docs/cli/authentication.md index 0a56bc58..a3d3c0f3 100644 --- a/docs/cli/authentication.md +++ b/docs/cli/authentication.md @@ -19,7 +19,7 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia ```bash export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" ``` - - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: + - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: ```bash echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc @@ -33,7 +33,7 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia ```bash export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" ``` - - For repeated use, you can add the environment variable to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: + - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: ```bash echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc source ~/.bashrc @@ -54,7 +54,7 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1 export GOOGLE_GENAI_USE_VERTEXAI=true ``` - - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file: + - For repeated use, you can add the environment variables to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file: ```bash echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc @@ -68,9 +68,43 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" export GOOGLE_GENAI_USE_VERTEXAI=true ``` - - For repeated use, you can add the environment variables to your `.env` file (located in the project directory or user home directory) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file: + - For repeated use, you can add the environment variables to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file: ```bash echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc source ~/.bashrc ``` + +### 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. + +Gemini CLI automatically loads environment variables from the **first** `.env` file it finds, using the following search order: + +1. Starting in the **current directory** and moving upward toward `/`, for each directory it checks: + 1. `.gemini/.env` + 2. `.env` +2. 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): + +```bash +mkdir -p .gemini +echo 'GOOGLE_CLOUD_PROJECT="your-project-id"' >> .gemini/.env +``` + +**User-wide settings** (available in every directory): + +```bash +mkdir -p ~/.gemini +cat >> ~/.gemini/.env <<'EOF' +GOOGLE_CLOUD_PROJECT="your-project-id" +GEMINI_API_KEY="your-gemini-api-key" +EOF +``` |