From dce25e4229edf7ec302dfe2ab2014184583cfa31 Mon Sep 17 00:00:00 2001 From: Chris Williams Date: Fri, 20 Mar 2026 14:07:33 -0700 Subject: [PATCH] Move docs into resources --- docs/resources/authentication.md | 416 +++++++++++++++++++++++++++++++ docs/resources/installation.md | 174 +++++++++++++ 2 files changed, 590 insertions(+) create mode 100644 docs/resources/authentication.md create mode 100644 docs/resources/installation.md diff --git a/docs/resources/authentication.md b/docs/resources/authentication.md new file mode 100644 index 0000000000..6d8758b958 --- /dev/null +++ b/docs/resources/authentication.md @@ -0,0 +1,416 @@ +# Gemini CLI authentication setup + +To use Gemini CLI, you'll need to authenticate with Google. This guide helps you +quickly find the best way to sign in based on your account type and how you're +using the CLI. + + +> [!TIP] +> Looking for a high-level comparison of all available subscriptions? +> To compare features and find the right quota for your needs, see our +> [Plans page](https://geminicli.com/plans/). + +For most users, we recommend starting Gemini CLI and logging in with your +personal Google account. + +## Choose your authentication method + +Select the authentication method that matches your situation in the table below: + +| User Type / Scenario | Recommended Authentication Method | Google Cloud Project Required | +| :--------------------------------------------------------------------- | :--------------------------------------------------------------- | :---------------------------------------------------------- | +| Individual Google accounts | [Sign in with Google](#login-google) | No, with exceptions | +| Organization users with a company, school, or Google Workspace account | [Sign in with Google](#login-google) | [Yes](#set-gcp) | +| AI Studio user with a Gemini API key | [Use Gemini API Key](#gemini-api) | No | +| Google Cloud Vertex AI user | [Vertex AI](#vertex-ai) | [Yes](#set-gcp) | +| [Headless mode](#headless) | [Use Gemini API Key](#gemini-api) or
[Vertex AI](#vertex-ai) | No (for Gemini API Key)
[Yes](#set-gcp) (for Vertex AI) | + +### What is my Google account type? + +- **Individual Google accounts:** Includes all + [free tier accounts](../resources/quota-and-pricing.md#free-usage) such as + Gemini Code Assist for individuals, as well as paid subscriptions for + [Google AI Pro and Ultra](https://gemini.google/subscriptions/). + +- **Organization accounts:** Accounts using paid licenses through an + organization such as a company, school, or + [Google Workspace](https://workspace.google.com/). Includes + [Google AI Ultra for Business](https://support.google.com/a/answer/16345165) + subscriptions. + +## (Recommended) Sign in with Google + +If you run Gemini CLI on your local machine, the simplest authentication method +is logging in with your Google account. This method requires a web browser on a +machine that can communicate with the terminal running Gemini CLI (for example, +your local machine). + +If you are a **Google AI Pro** or **Google AI Ultra** subscriber, use the Google +account associated with your subscription. + +To authenticate and use Gemini CLI: + +1. Start the CLI: + + ```bash + gemini + ``` + +2. Select **Sign in with Google**. Gemini CLI opens a sign in prompt using your + web browser. Follow the on-screen instructions. Your credentials will be + cached locally for future sessions. + +### Do I need to set my Google Cloud project? + +Most individual Google accounts (free and paid) don't require a Google Cloud +project for authentication. However, you'll need to set a Google Cloud project +when you meet at least one of the following conditions: + +- You are using a company, school, or Google Workspace account. +- You are using a Gemini Code Assist license from the Google Developer Program. +- You are using a license from a Gemini Code Assist subscription. + +For instructions, see [Set your Google Cloud Project](#set-gcp). + +## Use Gemini API key + +If you don't want to authenticate using your Google account, you can use an API +key from Google AI Studio. + +To authenticate and use Gemini CLI with a Gemini API key: + +1. Obtain your API key from + [Google AI Studio](https://aistudio.google.com/app/apikey). + +2. Set the `GEMINI_API_KEY` environment variable to your key. For example: + + **macOS/Linux** + + ```bash + # Replace YOUR_GEMINI_API_KEY with the key from AI Studio + export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" + ``` + + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_GEMINI_API_KEY with the key from AI Studio + $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY" + ``` + + To make this setting persistent, see + [Persisting Environment Variables](#persisting-vars). + +3. Start the CLI: + + ```bash + gemini + ``` + +4. Select **Use Gemini API key**. + + +> [!WARNING] +> Treat API keys, especially for services like Gemini, as sensitive +> credentials. Protect them to prevent unauthorized access and potential misuse +> of the service under your account. + +## Use Vertex AI + +To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the +following authentication options: + +- A. Application Default Credentials (ADC) using `gcloud`. +- B. Service account JSON key. +- C. Google Cloud API key. + +Regardless of your authentication method for Vertex AI, you'll need to set +`GOOGLE_CLOUD_PROJECT` to your Google Cloud project ID with the Vertex AI API +enabled, and `GOOGLE_CLOUD_LOCATION` to the location of your Vertex AI resources +or the location where you want to run your jobs. + +For example: + +**macOS/Linux** + +```bash +# Replace with your project ID and desired location (for example, us-central1) +export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" +export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" +``` + +**Windows (PowerShell)** + +```powershell +# Replace with your project ID and desired location (for example, us-central1) +$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" +$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" +``` + +To make any Vertex AI environment variable settings persistent, see +[Persisting Environment Variables](#persisting-vars). + +#### A. Vertex AI - application default credentials (ADC) using `gcloud` + +Consider this authentication method if you have Google Cloud CLI installed. + +If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset +them to use ADC. + +**macOS/Linux** + +```bash +unset GOOGLE_API_KEY GEMINI_API_KEY +``` + +**Windows (PowerShell)** + +```powershell +Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore +``` + +1. Verify you have a Google Cloud project and Vertex AI API is enabled. + +2. Log in to Google Cloud: + + ```bash + gcloud auth application-default login + ``` + +3. [Configure your Google Cloud Project](#set-gcp). + +4. Start the CLI: + + ```bash + gemini + ``` + +5. Select **Vertex AI**. + +#### B. Vertex AI - service account JSON key + +Consider this method of authentication in non-interactive environments, CI/CD +pipelines, or if your organization restricts user-based ADC or API key creation. + +If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset +them: + +**macOS/Linux** + +```bash +unset GOOGLE_API_KEY GEMINI_API_KEY +``` + +**Windows (PowerShell)** + +```powershell +Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore +``` + +1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete) + and download the provided JSON file. Assign the "Vertex AI User" role to the + service account. + +2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON + file's absolute path. For example: + + **macOS/Linux** + + ```bash + # Replace /path/to/your/keyfile.json with the actual path + export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" + ``` + + **Windows (PowerShell)** + + ```powershell + # Replace C:\path\to\your\keyfile.json with the actual path + $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json" + ``` + +3. [Configure your Google Cloud Project](#set-gcp). + +4. Start the CLI: + + ```bash + gemini + ``` + +5. Select **Vertex AI**. + + +> [!WARNING] +> Protect your service account key file as it gives access to +> your resources. + +#### C. Vertex AI - Google Cloud API key + +1. Obtain a Google Cloud API key: + [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser). + +2. Set the `GOOGLE_API_KEY` environment variable: + + **macOS/Linux** + + ```bash + # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key + export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" + ``` + + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key + $env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" + ``` + + If you see errors like `"API keys are not supported by this API..."`, your + organization might restrict API key usage for this service. Try the other + Vertex AI authentication methods instead. + +3. [Configure your Google Cloud Project](#set-gcp). + +4. Start the CLI: + + ```bash + gemini + ``` + +5. Select **Vertex AI**. + +## Set your Google Cloud project + + +> [!IMPORTANT] +> Most individual Google accounts (free and paid) don't require a +> Google Cloud project for authentication. + +When you sign in using your Google account, you may need to configure a Google +Cloud project for Gemini CLI to use. This applies when you meet at least one of +the following conditions: + +- You are using a Company, School, or Google Workspace account. +- You are using a Gemini Code Assist license from the Google Developer Program. +- You are using a license from a Gemini Code Assist subscription. + +To configure Gemini CLI to use a Google Cloud project, do the following: + +1. [Find your Google Cloud Project ID](https://support.google.com/googleapi/answer/7014113). + +2. [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api). + +3. [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam). + +4. Configure your environment variables. Set either the `GOOGLE_CLOUD_PROJECT` + or `GOOGLE_CLOUD_PROJECT_ID` variable to the project ID to use with Gemini + CLI. Gemini CLI checks for `GOOGLE_CLOUD_PROJECT` first, then falls back to + `GOOGLE_CLOUD_PROJECT_ID`. + + For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable: + + **macOS/Linux** + + ```bash + # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID + export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" + ``` + + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID + $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" + ``` + + To make this setting persistent, see + [Persisting Environment Variables](#persisting-vars). + +## Persisting environment variables + +To avoid setting environment variables for every terminal session, you can +persist them with the following methods: + +1. **Add your environment variables to your shell configuration file:** Append + the environment variable commands to your shell's startup file. + + **macOS/Linux** (for example, `~/.bashrc`, `~/.zshrc`, or `~/.profile`): + + ```bash + echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc + source ~/.bashrc + ``` + + **Windows (PowerShell)** (for example, `$PROFILE`): + + ```powershell + Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' + . $PROFILE + ``` + + +> [!WARNING] +> Be aware that when you export API keys or service account +> paths in your shell configuration file, any process launched from that +> shell can read them. + +2. **Use a `.env` file:** Create a `.gemini/.env` file in your project + directory or home directory. Gemini CLI automatically loads variables from + the first `.env` file it finds, searching up from the current directory, + then in your home directory's `.gemini/.env` (for example, `~/.gemini/.env` + or `%USERPROFILE%\.gemini\.env`). + + Example for user-wide settings: + + **macOS/Linux** + + ```bash + mkdir -p ~/.gemini + cat >> ~/.gemini/.env <<'EOF' + GOOGLE_CLOUD_PROJECT="your-project-id" + # Add other variables like GEMINI_API_KEY as needed + EOF + ``` + + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini" + @" + GOOGLE_CLOUD_PROJECT="your-project-id" + # Add other variables like GEMINI_API_KEY as needed + "@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append + ``` + +Variables are loaded from the first file found, not merged. + +## Running in Google Cloud environments + +When running Gemini CLI within certain Google Cloud environments, authentication +is automatic. + +In a Google Cloud Shell environment, Gemini CLI typically authenticates +automatically using your Cloud Shell credentials. In Compute Engine +environments, Gemini CLI automatically uses Application Default Credentials +(ADC) from the environment's metadata server. + +If automatic authentication fails, use one of the interactive methods described +on this page. + +## Running in headless mode + +[Headless mode](../cli/headless) will use your existing authentication method, +if an existing authentication credential is cached. + +If you have not already signed in with an authentication credential, you must +configure authentication using environment variables: + +- [Use Gemini API Key](#gemini-api) +- [Vertex AI](#vertex-ai) + +## What's next? + +Your authentication method affects your quotas, pricing, Terms of Service, and +privacy notices. Review the following pages to learn more: + +- [Gemini CLI: Quotas and Pricing](../resources/quota-and-pricing.md). +- [Gemini CLI: Terms of Service and Privacy Notice](../resources/tos-privacy.md). diff --git a/docs/resources/installation.md b/docs/resources/installation.md new file mode 100644 index 0000000000..e56d98d889 --- /dev/null +++ b/docs/resources/installation.md @@ -0,0 +1,174 @@ +# Gemini CLI installation, execution, and releases + +This document provides an overview of Gemini CLI's system requirements, +installation methods, and release types. + +## Recommended system specifications + +- **Operating System:** + - macOS 15+ + - Windows 11 24H2+ + - Ubuntu 20.04+ +- **Hardware:** + - "Casual" usage: 4GB+ RAM (short sessions, common tasks and edits) + - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context) +- **Runtime:** Node.js 20.0.0+ +- **Shell:** Bash, Zsh, or PowerShell +- **Location:** + [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) +- **Internet connection required** + +## Install Gemini CLI + +We recommend most users install Gemini CLI using one of the following +installation methods: + +- npm +- Homebrew +- MacPorts +- Anaconda + +Note that Gemini CLI comes pre-installed on +[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and +[**Cloud Workstations**](https://cloud.google.com/workstations). + +### Install globally with npm + +```bash +npm install -g @google/gemini-cli +``` + +### Install globally with Homebrew (macOS/Linux) + +```bash +brew install gemini-cli +``` + +### Install globally with MacPorts (macOS) + +```bash +sudo port install gemini-cli +``` + +### Install with Anaconda (for restricted environments) + +```bash +# Create and activate a new environment +conda create -y -n gemini_env -c conda-forge nodejs +conda activate gemini_env + +# Install Gemini CLI globally via npm (inside the environment) +npm install -g @google/gemini-cli +``` + +## Run Gemini CLI + +For most users, we recommend running Gemini CLI with the `gemini` command: + +```bash +gemini +``` + +For a list of options and additional commands, see the +[CLI cheatsheet](../cli/cli-reference.md). + +You can also run Gemini CLI using one of the following advanced methods: + +- Run instantly with npx. You can run Gemini CLI without permanent installation. +- In a sandbox. This method offers increased security and isolation. +- From the source. This is recommended for contributors to the project. + +### Run instantly with npx + +```bash +# Using npx (no installation required) +npx @google/gemini-cli +``` + +You can also execute the CLI directly from the main branch on GitHub, which is +helpful for testing features still in development: + +```bash +npx https://github.com/google-gemini/gemini-cli +``` + +### Run in a sandbox (Docker/Podman) + +For security and isolation, Gemini CLI can be run inside a container. This is +the default way that the CLI executes tools that might have side effects. + +- **Directly from the registry:** You can run the published sandbox image + directly. This is useful for environments where you only have Docker and want + to run the CLI. + ```bash + # Run the published sandbox image + docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1 + ``` +- **Using the `--sandbox` flag:** If you have Gemini CLI installed locally + (using the standard installation described above), you can instruct it to run + inside the sandbox container. + ```bash + gemini --sandbox -y -p "your prompt here" + ``` + +### Run from source (recommended for Gemini CLI contributors) + +Contributors to the project will want to run the CLI directly from the source +code. + +- **Development mode:** This method provides hot-reloading and is useful for + active development. + ```bash + # From the root of the repository + npm run start + ``` +- **Production-like mode (linked package):** This method simulates a global + installation by linking your local package. It's useful for testing a local + build in a production workflow. + + ```bash + # Link the local cli package to your global node_modules + npm link packages/cli + + # Now you can run your local version using the `gemini` command + gemini + ``` + +## Releases + +Gemini CLI has three release channels: nightly, preview, and stable. For most +users, we recommend the stable release, which is the default installation. + +### Stable + +New stable releases are published each week. The stable release is the promotion +of last week's `preview` release along with any bug fixes. The stable release +uses `latest` tag, but omitting the tag also installs the latest stable release +by default: + +```bash +# Both commands install the latest stable release. +npm install -g @google/gemini-cli +npm install -g @google/gemini-cli@latest +``` + +### Preview + +New preview releases will be published each week. These releases are not fully +vetted and may contain regressions or other outstanding issues. Try out the +preview release by using the `preview` tag: + +```bash +npm install -g @google/gemini-cli@preview +``` + +### Nightly + +Nightly releases are published every day. The nightly release includes all +changes from the main branch at time of release. It should be assumed there are +pending validations and issues. You can help test the latest changes by +installing with the `nightly` tag: + +```bash +npm install -g @google/gemini-cli@nightly +```