diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index 5e9cede33a..f083353a6d 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -508,7 +508,7 @@ other events. For more information, see the You can enforce a specific authentication method for all users by setting the `enforcedAuthType` in the system-level `settings.json` file. This prevents users from choosing a different authentication method. See the -[Authentication docs](../get-started/authentication.md) for more details. +[Authentication docs](../resources/authentication.md) for more details. **Example:** Enforce the use of Google login for all users. diff --git a/docs/cli/system-prompt.md b/docs/cli/system-prompt.md index c249d55cec..199a8e0ed2 100644 --- a/docs/cli/system-prompt.md +++ b/docs/cli/system-prompt.md @@ -24,7 +24,7 @@ project-specific behavior or create a customized persona. You can set the environment variable temporarily in your shell, or persist it via a `.gemini/.env` file. See -[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables). +[Persisting Environment Variables](../resources/authentication.md#persisting-environment-variables). - Use the project default path (`.gemini/system.md`): - `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1` diff --git a/docs/get-started/authentication.md b/docs/get-started/authentication.md deleted file mode 100644 index 6d8758b958..0000000000 --- a/docs/get-started/authentication.md +++ /dev/null @@ -1,416 +0,0 @@ -# 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/get-started/index.md b/docs/get-started/index.md index 566ac6e9df..fdee2b5506 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -24,7 +24,8 @@ Once Gemini CLI is installed, run Gemini CLI from your command line: gemini ``` -For more installation options, see [Gemini CLI Installation](./installation.md). +For more installation options, see +[Gemini CLI Installation](../resources/installation.md). ## Authenticate @@ -46,7 +47,7 @@ cases, you can log in with your existing Google account: Certain account types may require you to configure a Google Cloud project. For more information, including other authentication methods, see -[Gemini CLI Authentication Setup](./authentication.md). +[Gemini CLI Authentication Setup](../resources/authentication.md). ## Configure diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md deleted file mode 100644 index e56d98d889..0000000000 --- a/docs/get-started/installation.md +++ /dev/null @@ -1,174 +0,0 @@ -# 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 -``` diff --git a/docs/index.md b/docs/index.md index af1915bb8f..7a367a24c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,15 +10,15 @@ context. npm install -g @google/gemini-cli ``` +For more installation options and authentication setup, see the full +[Installation](./resources/installation.md) and +[Authentication](./resources/authentication.md) guides. + ## Get started Jump in to Gemini CLI. - **[Quickstart](./get-started/index.md):** Your first session with Gemini CLI. -- **[Installation](./get-started/installation.md):** How to install Gemini CLI - on your system. -- **[Authentication](./get-started/authentication.md):** Setup instructions for - personal and enterprise accounts. - **[Examples](./get-started/examples.md):** Practical examples of Gemini CLI in action. - **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common @@ -116,6 +116,9 @@ Deep technical documentation and API specifications. Support, release history, and legal information. - **[FAQ](./resources/faq.md):** Answers to frequently asked questions. +- **[Installation](./resources/installation.md):** How to install Gemini CLI. +- **[Authentication](./resources/authentication.md):** Setup instructions for + personal and enterprise accounts. - **[Quota and pricing](./resources/quota-and-pricing.md):** Limits and billing details. - **[Terms and privacy](./resources/tos-privacy.md):** Official notices and diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 5791bbf457..1e3e7b4120 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1903,8 +1903,8 @@ within your user's home folder. Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments. For authentication setup, see the -[Authentication documentation](../get-started/authentication.md) which covers -all available authentication methods. +[Authentication documentation](../resources/authentication.md) which covers all +available authentication methods. The CLI automatically loads environment variables from an `.env` file. The loading order is: @@ -1924,7 +1924,7 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. - **`GEMINI_API_KEY`**: - Your API key for the Gemini API. - One of several available - [authentication methods](../get-started/authentication.md). + [authentication methods](../resources/authentication.md). - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file. - **`GEMINI_MODEL`**: diff --git a/docs/sidebar.json b/docs/sidebar.json index 7198a0336b..dddf47d2c1 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -7,11 +7,6 @@ "items": [ { "label": "Overview", "slug": "docs" }, { "label": "Quickstart", "slug": "docs/get-started" }, - { "label": "Installation", "slug": "docs/get-started/installation" }, - { - "label": "Authentication", - "slug": "docs/get-started/authentication" - }, { "label": "Examples", "slug": "docs/get-started/examples" }, { "label": "CLI cheatsheet", "slug": "docs/cli/cli-reference" }, { @@ -220,6 +215,11 @@ "label": "Resources", "items": [ { "label": "FAQ", "slug": "docs/resources/faq" }, + { "label": "Installation", "slug": "docs/resources/installation" }, + { + "label": "Authentication", + "slug": "docs/resources/authentication" + }, { "label": "Quota and pricing", "slug": "docs/resources/quota-and-pricing"