From 220888ac2dfd40733bc51ea6b8550c3a0777673c Mon Sep 17 00:00:00 2001 From: Sam Roberts <158088236+g-samroberts@users.noreply.github.com> Date: Fri, 17 Apr 2026 11:07:07 -0700 Subject: [PATCH] docs: migrate installation and authentication to mdx with tabbed layouts (#25155) --- .gemini/skills/docs-writer/SKILL.md | 21 +- .prettierignore | 1 + docs/cli/enterprise.md | 2 +- docs/cli/system-prompt.md | 2 +- .../{authentication.md => authentication.mdx} | 226 +++++++++++------- docs/get-started/index.md | 5 +- docs/get-started/installation.md | 181 -------------- docs/get-started/installation.mdx | 201 ++++++++++++++++ docs/index.md | 4 +- docs/reference/configuration.md | 4 +- 10 files changed, 362 insertions(+), 285 deletions(-) rename docs/get-started/{authentication.md => authentication.mdx} (76%) delete mode 100644 docs/get-started/installation.md create mode 100644 docs/get-started/installation.mdx diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md index 64aea85d07..5772e7fb3d 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -85,17 +85,25 @@ accessible. - **Callouts**: Use GitHub-flavored markdown alerts to highlight important information. To ensure the formatting is preserved by `npm run format`, place - an empty line, then the `` comment directly before - the callout block. The callout type (`[!TYPE]`) should be on the first line, - followed by a newline, and then the content, with each subsequent line of - content starting with `>`. Available types are `NOTE`, `TIP`, `IMPORTANT`, - `WARNING`, and `CAUTION`. + an empty line, then a prettier ignore comment directly before the callout + block. Use `` for standard Markdown files (`.md`) and + `{/* prettier-ignore */}` for MDX files (`.mdx`). The callout type (`[!TYPE]`) + should be on the first line, followed by a newline, and then the content, with + each subsequent line of content starting with `>`. Available types are `NOTE`, + `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`. - Example: + Example (.md): > [!NOTE] > This is an example of a multi-line note that will be preserved +> by Prettier. + + Example (.mdx): + +{/* prettier-ignore */} +> [!NOTE] +> This is an example of a multi-line note that will be preserved > by Prettier. ### Links @@ -118,6 +126,7 @@ accessible. > [!NOTE] > This is an experimental feature currently under active development. +(Note: Use `{/* prettier-ignore */}` if editing an `.mdx` file.) - **Headings:** Use hierarchical headings to support the user journey. - **Procedures:** diff --git a/.prettierignore b/.prettierignore index 9009498d8d..78066b7e78 100644 --- a/.prettierignore +++ b/.prettierignore @@ -22,3 +22,4 @@ Thumbs.db .pytest_cache **/SKILL.md packages/sdk/test-data/*.json +*.mdx diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index daea2eca01..1222591fc9 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -507,7 +507,7 @@ events. For more information, see the [telemetry documentation](./telemetry.md). You can enforce a specific authentication method for all users by setting the `security.auth.enforcedType` 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](../get-started/authentication.mdx) 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 6d6388bc87..e9e87f07d9 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](../get-started/authentication.mdx#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.mdx similarity index 76% rename from docs/get-started/authentication.md rename to docs/get-started/authentication.mdx index 31f2fff540..e74e243483 100644 --- a/docs/get-started/authentication.md +++ b/docs/get-started/authentication.mdx @@ -1,10 +1,11 @@ +import { Tabs, TabItem } from '@astrojs/starlight/components'; + # 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 @@ -23,7 +24,7 @@ Select the authentication method that matches your situation in the table below: | 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) | +| [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? @@ -84,19 +85,24 @@ To authenticate and use Gemini CLI with a Gemini API key: 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" - ``` + ```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" - ``` + ```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). @@ -109,7 +115,6 @@ To authenticate and use Gemini CLI with a Gemini API key: 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 @@ -131,21 +136,26 @@ or the location where you want to run your jobs. For example: -**macOS/Linux** + + -```bash + ```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 + ```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). @@ -157,17 +167,22 @@ 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 + ```bash unset GOOGLE_API_KEY GEMINI_API_KEY -``` + ``` -**Windows (PowerShell)** + + -```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. @@ -195,17 +210,22 @@ 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 + ```bash unset GOOGLE_API_KEY GEMINI_API_KEY -``` + ``` -**Windows (PowerShell)** + + -```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 @@ -214,19 +234,24 @@ Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore 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" - ``` + ```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" - ``` + ```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). @@ -238,7 +263,6 @@ Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore 5. Select **Vertex AI**. - > [!WARNING] > Protect your service account key file as it gives access to > your resources. @@ -250,19 +274,24 @@ Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore 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" - ``` + ```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" - ``` + ```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 @@ -280,7 +309,6 @@ Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore ## Set your Google Cloud project - > [!IMPORTANT] > Most individual Google accounts (free and paid) don't require a > Google Cloud project for authentication. @@ -308,19 +336,24 @@ To configure Gemini CLI to use a Google Cloud project, do the following: 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" - ``` + ```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" - ``` + ```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). @@ -333,21 +366,29 @@ 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 - ``` + (for example, `~/.bashrc`, `~/.zshrc`, or `~/.profile`): - **Windows (PowerShell)** (for example, `$PROFILE`): + ```bash + echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc + source ~/.bashrc + ``` - ```powershell - Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' - . $PROFILE - ``` + + + + (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 @@ -361,25 +402,30 @@ persist them with the following methods: 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 - ``` + ```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 - ``` + ```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. diff --git a/docs/get-started/index.md b/docs/get-started/index.md index c6ea5ea4ae..90cc78d40a 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](./installation.mdx). ## 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](./authentication.mdx). ## Configure diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md deleted file mode 100644 index 15922a6b8e..0000000000 --- a/docs/get-started/installation.md +++ /dev/null @@ -1,181 +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 mode (React optimizations):** This method runs the CLI with React - production mode enabled, which is useful for testing performance without - development overhead. - ```bash - # From the root of the repository - npm run start:prod - ``` -- **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/get-started/installation.mdx b/docs/get-started/installation.mdx new file mode 100644 index 0000000000..eaf175e30a --- /dev/null +++ b/docs/get-started/installation.mdx @@ -0,0 +1,201 @@ +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +# 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. 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: + + ```bash + brew install gemini-cli + ``` + + + + + Install globally with MacPorts: + + ```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. + + ```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 + ``` + + + + + 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" + ``` + + + + + 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 mode (React optimizations):** This method runs the CLI with React + production mode enabled, which is useful for testing performance without + development overhead. + ```bash + # From the root of the repository + npm run start:prod + ``` + - **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: stable, preview, and nightly. For most +users, we recommend the stable release, which is the default installation. + + + + + Stable releases are published each week. A stable release is created from the + previous week's preview release along with any bug fixes. The stable release + uses the `latest` tag. 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 + ``` + + + + + 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 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 d1c1febf55..d5fefce47c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,9 +15,9 @@ npm install -g @google/gemini-cli 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 +- **[Installation](./get-started/installation.mdx):** How to install Gemini CLI on your system. -- **[Authentication](./get-started/authentication.md):** Setup instructions for +- **[Authentication](./get-started/authentication.mdx):** Setup instructions for personal and enterprise accounts. - **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common commands and options. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index a6eba98189..0b7b23c4e9 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -2079,7 +2079,7 @@ 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 +[Authentication documentation](../get-started/authentication.mdx) which covers all available authentication methods. The CLI automatically loads environment variables from an `.env` file. The @@ -2100,7 +2100,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](../get-started/authentication.mdx). - Set this in your shell profile (for example, `~/.bashrc`, `~/.zshrc`) or an `.env` file. - **`GEMINI_MODEL`**: