diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md
index 2a814b87bc..d6c3b0f54c 100644
--- a/.gemini/skills/docs-writer/SKILL.md
+++ b/.gemini/skills/docs-writer/SKILL.md
@@ -86,16 +86,23 @@ 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,
+ the callout block (for `.mdx` files, use `{/* prettier-ignore */}`). 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
diff --git a/docs/get-started/authentication.md b/docs/get-started/authentication.md
index 31f2fff540..a018c2405d 100644
--- a/docs/get-started/authentication.md
+++ b/docs/get-started/authentication.md
@@ -1,3 +1,5 @@
+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
@@ -84,19 +86,20 @@ 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"
- ```
-
- **Windows (PowerShell)**
-
- ```powershell
- # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
- $env: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"
+ ```
+
+
+ ```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).
@@ -131,21 +134,22 @@ 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"
-```
+
+
+ ```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"
+ ```
+
+
+ ```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 +161,18 @@ 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
-```
+
+
+ ```bash
+ unset GOOGLE_API_KEY GEMINI_API_KEY
+ ```
+
+
+ ```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 +200,18 @@ 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
-```
+
+
+ ```bash
+ unset GOOGLE_API_KEY GEMINI_API_KEY
+ ```
+
+
+ ```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 +220,20 @@ 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"
- ```
-
- **Windows (PowerShell)**
-
- ```powershell
- # Replace C:\path\to\your\keyfile.json with the actual path
- $env:GOOGLE_APPLICATION_CREDENTIALS="C:\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"
+ ```
+
+
+ ```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).
@@ -250,19 +257,20 @@ 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"
- ```
-
- **Windows (PowerShell)**
-
- ```powershell
- # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
- $env: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"
+ ```
+
+
+ ```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
@@ -308,19 +316,20 @@ 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"
- ```
-
- **Windows (PowerShell)**
-
- ```powershell
- # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
- $env: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"
+ ```
+
+
+ ```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,19 +342,20 @@ 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
- ```
+
+
+ ```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
+ ```
+
+
> [!WARNING]
@@ -361,25 +371,26 @@ 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
- ```
-
- **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
- ```
+
+
+ ```bash
+ mkdir -p ~/.gemini
+ cat >> ~/.gemini/.env <<'EOF'
+ GOOGLE_CLOUD_PROJECT="your-project-id"
+ # Add other variables like GEMINI_API_KEY as needed
+ EOF
+ ```
+
+
+ ```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/installation.md b/docs/get-started/installation.md
index 15922a6b8e..2cbac10de0 100644
--- a/docs/get-started/installation.md
+++ b/docs/get-started/installation.md
@@ -1,3 +1,5 @@
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
# Gemini CLI installation, execution, and releases
This document provides an overview of Gemini CLI's system requirements,
@@ -32,25 +34,33 @@ 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
+
+
+ Install globally with npm:
```bash
npm install -g @google/gemini-cli
```
-### Install globally with Homebrew (macOS/Linux)
+
+
+ Install globally with Homebrew (macOS/Linux):
```bash
brew install gemini-cli
```
-### Install globally with MacPorts (macOS)
+
+
+ Install globally with MacPorts (macOS):
```bash
sudo port install gemini-cli
```
-### Install with Anaconda (for restricted environments)
+
+
+ Install with Anaconda (for restricted environments):
```bash
# Create and activate a new environment
@@ -61,27 +71,24 @@ conda activate gemini_env
npm install -g @google/gemini-cli
```
+
+
+
## Run Gemini CLI
-For most users, we recommend running Gemini CLI with the `gemini` command:
+
+
+ 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
+[CLI cheatsheet](../cli/cli-reference.md). Run
+instantly with npx (no permanent installation required).
```bash
-# Using npx (no installation required)
npx @google/gemini-cli
```
@@ -92,10 +99,10 @@ helpful for testing features still in development:
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.
+
+
+ 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
@@ -107,14 +114,15 @@ the default way that the CLI executes tools that might have side effects.
- **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.
+
+
+ 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.
@@ -133,25 +141,28 @@ code.
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
+ ```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
- ```
+ # 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:
+
+
+ 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.
@@ -159,23 +170,26 @@ 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:
+
+
+ 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:
+
+
+ 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
```
+
+
+