From e423d20a8d57d422eef1e9364cee26478f3e4a7d Mon Sep 17 00:00:00 2001 From: Bryan Morgan Date: Mon, 23 Jun 2025 17:55:24 -0400 Subject: [PATCH] Updated docs and /stats command to support lack of token caching support for OAuth users (b/426943001) (#1307) --- README.md | 113 ++++++++++++++++-- docs/cli/commands.md | 2 +- docs/troubleshooting.md | 4 + packages/cli/src/ui/components/Stats.tsx | 12 +- .../SessionSummaryDisplay.test.tsx.snap | 1 - .../__snapshots__/StatsDisplay.test.tsx.snap | 1 - 6 files changed, 117 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 24ff6cc5..78f75745 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,111 @@ Or ask it to perform a task using its tools: > List files in the current directory. ``` -Take a look at some [popular tasks](#popular-tasks) for more inspiration. +## API Key Setup + +The Gemini CLI requires you to authenticate with Google's AI services. You'll need to configure **one** of the following authentication methods: + +1. **Gemini Code Assist:** + + - To enable this mode you only need set the GEMINI_CODE_ASSIST environment variable to true. + - You can temporarily set the environment variable in your current shell session using the following command: + ```bash + export GEMINI_CODE_ASSIST="true" + ``` + - 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_CODE_ASSIST="true"' >> ~/.bashrc + source ~/.bashrc + ``` + - There are two types of Google Accounts you can use with Gemini CLI: + - **Personal Google Account**: This is the standard, free account you use for services like Gmail, Google Photos, and Google Drive for personal use (e.g. your-name@gmail.com). + - **Google Workspace Account**: This 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. + - 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 start up, 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. Cached credentials last about 20 hours before expiring. + - Note that the 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. **Google API Key (Vertex AI Express Mode):** + + - You can use a general Google Cloud API key if it has been enabled for the Gemini API or Vertex AI. + - Set the `GOOGLE_API_KEY` and `GOOGLE_GENAI_USE_VERTEXAI` environment variables. In the following methods, replace `YOUR_GEMINI_API_KEY` with your Google Cloud API key: + - 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 GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc + echo 'export GOOGLE_GENAI_USE_VERTEXAI=true' >> ~/.bashrc + source ~/.bashrc + ``` + +4. **Vertex AI (Project and Location):** + - 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 + ``` + +## Token Caching and Cost Optimization + +Gemini CLI automatically optimizes API costs through token caching when using API key authentication (Gemini API key or Vertex AI). This feature reuses previous system instructions and context to reduce the number of tokens processed in subsequent requests. + +**Token caching is available for:** + +- API key users (Gemini API key) +- Vertex AI users (with project and location setup) + +**Token caching is not available for:** + +- OAuth users (Google Personal/Enterprise accounts) - the Code Assist API does not support cached content creation at this time + +You can view your token usage and cached token savings using the `/stats` command. When cached tokens are available, they will be displayed in the stats output. + +### Next steps + +- Learn how to [contribute to or build from the source](./CONTRIBUTING.md). +- Explore the available **[CLI Commands](./docs/cli/commands.md)**. +- If you encounter any issues, review the **[Troubleshooting guide](./docs/troubleshooting.md)**. +- For more comprehensive documentation, see the [full documentation](./docs/index.md). +- Take a look at some [popular tasks](#popular-tasks) for more inspiration. ## Popular tasks @@ -92,13 +196,6 @@ Use MCP servers to integrate your local system tools with your enterprise collab > Organise my PDF invoices by month of expenditure. ``` -### Next steps - -- Learn how to [contribute to or build from the source](./CONTRIBUTING.md). -- Explore the available **[CLI Commands](./docs/cli/commands.md)**. -- If you encounter any issues, review the **[Troubleshooting guide](./docs/troubleshooting.md)**. -- For more comprehensive documentation, see the [full documentation](./docs/index.md). - ## Gemini APIs This project leverages the Gemini APIs to provide AI capabilities. For details on the terms of service governing the Gemini API, please refer to the [Gemini API Terms of Service](https://ai.google.dev/gemini-api/terms). diff --git a/docs/cli/commands.md b/docs/cli/commands.md index b4225f76..ad6254a4 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -72,7 +72,7 @@ Slash commands provide meta-level control over the CLI itself. - **`/stats`** - - **Description:** Display detailed statistics for the current Gemini CLI session, such as the session duration. + - **Description:** Display detailed statistics for the current Gemini CLI session, including token usage, cached token savings (when available), and session duration. Note: Cached token information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication at this time. - [**`/theme`**](./themes.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c84e68c7..7dbda1b8 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -12,6 +12,10 @@ This guide provides solutions to common issues and debugging tips. - A: The CLI configuration is stored within two `settings.json` files: one in your home directory and one in your project's root directory. In both locations, `settings.json` is found in the `.gemini/` folder. Refer to [CLI Configuration](./cli/configuration.md) for more details. +- **Q: Why don't I see cached token counts in my stats output?** + + - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Vertex AI) but not for OAuth users (Google Personal/Enterprise accounts) at this time, as the Code Assist API does not support cached content creation. You can still view your total token usage with the `/stats` command. + ## Common error messages and solutions - **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.** diff --git a/packages/cli/src/ui/components/Stats.tsx b/packages/cli/src/ui/components/Stats.tsx index 64e55d8b..d620416e 100644 --- a/packages/cli/src/ui/components/Stats.tsx +++ b/packages/cli/src/ui/components/Stats.tsx @@ -76,11 +76,13 @@ export const StatsColumn: React.FC<{ label="Thoughts Tokens" value={stats.thoughtsTokens.toLocaleString()} /> - + {stats.cachedTokens > 0 && ( + + )} {/* Divider Line */} > renders zero state correctly 1`] = ` │ Input Tokens 0 │ │ Output Tokens 0 │ │ Thoughts Tokens 0 │ -│ Cached Tokens 0 │ │ ────────────────────────── │ │ Total Tokens 0 │ │ │ diff --git a/packages/cli/src/ui/components/__snapshots__/StatsDisplay.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/StatsDisplay.test.tsx.snap index 8dc73d93..b8a070a3 100644 --- a/packages/cli/src/ui/components/__snapshots__/StatsDisplay.test.tsx.snap +++ b/packages/cli/src/ui/components/__snapshots__/StatsDisplay.test.tsx.snap @@ -31,7 +31,6 @@ exports[` > renders zero state correctly 1`] = ` │ Input Tokens 0 Input Tokens 0 │ │ Output Tokens 0 Output Tokens 0 │ │ Thoughts Tokens 0 Thoughts Tokens 0 │ -│ Cached Tokens 0 Cached Tokens 0 │ │ ───────────────────────────────────────────── ───────────────────────────────────────────── │ │ Total Tokens 0 Total Tokens 0 │ │ │