Docs/authentication doc (#1341)

2 files changed, 75 insertions, 0 deletions

diff --git a/docs/cli/authentication.md b/docs/cli/authentication.md
new file mode 100644
index 00000000..f1a8ba58
--- /dev/null
+++ b/docs/cli/authentication.md
@@ -0,0 +1,74 @@
+## Authentication Setup
+
+The Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure **one** of the following authentication methods:
+
+1.  **Login with Google (Gemini Code Assist):**
+
+    - Use this option to log in with the standard, free account you use for services like Gmail, Google Photos, and Google Drive for personal use (e.g. [email protected]).
+    - During initial startup, Gemini CLI 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 Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on).
+
+2.  **Gemini API key:**
+
+    - Obtain your API key from Google AI Studio: [https://aistudio.google.com/app/apikey](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:
+        ```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:
+        ```bash
+        echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
+        source ~/.bashrc
+        ```
+
+3.  **Login with Google Work**
+
+    - Use this option to log in with the **Google Workspace Accounts**. This is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. [email protected]), enhanced security features, and administrative controls. These accounts are often managed by an employer or school.
+      - Google Workspace Account must configure a Google Cloud Project Id to use. You can temporarily set the environment variable in your current shell session using the following command:
+      ```bash
+      export GOOGLE_CLOUD_PROJECT_ID="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:
+      ```bash
+      echo 'export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"' >> ~/.bashrc
+      source ~/.bashrc
+      ```
+    - During startup, Gemini CLI 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 Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on).
+
+4.  **Vertex AI:**
+    - If not using express mode:
+      - Ensure you have a Google Cloud project and have enabled the Vertex AI API.
+      - Set up Application Default Credentials (ADC), using the following command:
+        ```bash
+        gcloud auth application-default login
+        ```
+        For more information, see [Set up Application Default Credentials for Google Cloud](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+      - Set the `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI` 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:
+          ```bash
+          export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+          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 adds 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
+          echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc
+          source ~/.bashrc
+          ```
+    - If using express mode:
+      - Set the `GOOGLE_API_KEY` environment variables. In the following methods, replace `YOUR_GOOGLE_API_KEY` with your Vertex AI API key provided by express mode:
+        - You can temporarily set these environment variables in your current shell session using the following commands:
+          ```bash
+          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 adds 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
+          ```
diff --git a/docs/cli/index.md b/docs/cli/index.md
index e0b41096..430548b9 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -4,6 +4,7 @@ Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
 
 ## Navigating this section
 
+- **[Authentication](./authentication.md):** A guide to setting up authentication with Google's AI services.
 - **[Commands](./commands.md):** A reference for Gemini CLI commands (e.g., `/help`, `/tools`, `/theme`).
 - **[Configuration](./configuration.md):** A guide to tailoring Gemini CLI behavior using configuration files.
 - **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes.