Elgato_dark/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli synced 2026-04-21 13:37:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 19

docs: migrate installation and authentication to mdx with tabbed layouts (#25155)

Browse source
This commit is contained in:
Sam Roberts 2026-04-17 11:07:07 -07:00 committed by GitHub
parent b2f775921d
commit 220888ac2d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 362 additions and 285 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
.gemini/skills/docs-writer/SKILL.md
View file

@ -85,17 +85,25 @@ accessible.
- **Callouts**: Use GitHub-flavored markdown alerts to highlight important - **Callouts**: Use GitHub-flavored markdown alerts to highlight important
information. To ensure the formatting is preserved by `npm run format`, place information. To ensure the formatting is preserved by `npm run format`, place
an empty line, then the `<!-- prettier-ignore -->` comment directly before an empty line, then a prettier ignore comment directly before the callout
the callout block. The callout type (`[!TYPE]`) should be on the first line, block. Use `<!-- prettier-ignore -->` for standard Markdown files (`.md`) and
followed by a newline, and then the content, with each subsequent line of `{/* prettier-ignore */}` for MDX files (`.mdx`). The callout type (`[!TYPE]`)
content starting with `>`. Available types are `NOTE`, `TIP`, `IMPORTANT`, should be on the first line, followed by a newline, and then the content, with
`WARNING`, and `CAUTION`. each subsequent line of content starting with `>`. Available types are `NOTE`,
`TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
Example: Example (.md):
<!-- prettier-ignore --> <!-- prettier-ignore -->
> [!NOTE] > [!NOTE]
> This is an example of a multi-line note that will be preserved > 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. > by Prettier.
### Links ### Links
@ -118,6 +126,7 @@ accessible.
<!-- prettier-ignore --> <!-- prettier-ignore -->
> [!NOTE] > [!NOTE]
> This is an experimental feature currently under active development. > 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. - **Headings:** Use hierarchical headings to support the user journey.
- **Procedures:** - **Procedures:**

1
.prettierignore
View file

@ -22,3 +22,4 @@ Thumbs.db
.pytest_cache .pytest_cache
**/SKILL.md **/SKILL.md
packages/sdk/test-data/*.json packages/sdk/test-data/*.json
*.mdx

2
docs/cli/enterprise.md
View file

@ -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 You can enforce a specific authentication method for all users by setting the
`security.auth.enforcedType` in the system-level `settings.json` file. This `security.auth.enforcedType` in the system-level `settings.json` file. This
prevents users from choosing a different authentication method. See the 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. **Example:** Enforce the use of Google login for all users.

2
docs/cli/system-prompt.md
View file

@ -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 You can set the environment variable temporarily in your shell, or persist it
via a `.gemini/.env` file. See 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`): - Use the project default path (`.gemini/system.md`):
- `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1` - `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1`

226
docs/get-started/authentication.md → docs/get-started/authentication.mdx
View file

@ -1,10 +1,11 @@
import { Tabs, TabItem } from '@astrojs/starlight/components';
# Gemini CLI authentication setup # Gemini CLI authentication setup
To use Gemini CLI, you'll need to authenticate with Google. This guide helps you 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 quickly find the best way to sign in based on your account type and how you're
using the CLI. using the CLI.
<!-- prettier-ignore -->
> [!TIP] > [!TIP]
> Looking for a high-level comparison of all available subscriptions? > Looking for a high-level comparison of all available subscriptions?
> To compare features and find the right quota for your needs, see our > 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) | | 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 | | 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) | | Google Cloud Vertex AI user | [Vertex AI](#vertex-ai) | [Yes](#set-gcp) |
| [Headless mode](#headless) | [Use Gemini API Key](#gemini-api) or<br> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br> [Yes](#set-gcp) (for Vertex AI) | | [Headless mode](#headless) | [Use Gemini API Key](#gemini-api) or<br /> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br /> [Yes](#set-gcp) (for Vertex AI) |
### What is my Google account type? ### 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: 2. Set the `GEMINI_API_KEY` environment variable to your key. For example:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
# Replace YOUR_GEMINI_API_KEY with the key from AI Studio # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
# Replace YOUR_GEMINI_API_KEY with the key from AI Studio # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
$env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY" $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
``` ```
</TabItem>
</Tabs>
To make this setting persistent, see To make this setting persistent, see
[Persisting Environment Variables](#persisting-vars). [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**. 4. Select **Use Gemini API key**.
<!-- prettier-ignore -->
> [!WARNING] > [!WARNING]
> Treat API keys, especially for services like Gemini, as sensitive > Treat API keys, especially for services like Gemini, as sensitive
> credentials. Protect them to prevent unauthorized access and potential misuse > 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: For example:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
# Replace with your project ID and desired location (for example, us-central1) # Replace with your project ID and desired location (for example, us-central1)
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
# Replace with your project ID and desired location (for example, us-central1) # Replace with your project ID and desired location (for example, us-central1)
$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" $env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
``` ```
</TabItem>
</Tabs>
To make any Vertex AI environment variable settings persistent, see To make any Vertex AI environment variable settings persistent, see
[Persisting Environment Variables](#persisting-vars). [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 If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset
them to use ADC. them to use ADC.
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
unset GOOGLE_API_KEY GEMINI_API_KEY unset GOOGLE_API_KEY GEMINI_API_KEY
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
``` ```
</TabItem>
</Tabs>
1. Verify you have a Google Cloud project and Vertex AI API is enabled. 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 If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset
them: them:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
unset GOOGLE_API_KEY GEMINI_API_KEY unset GOOGLE_API_KEY GEMINI_API_KEY
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
``` ```
</TabItem>
</Tabs>
1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete) 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 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 2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON
file's absolute path. For example: file's absolute path. For example:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
# Replace /path/to/your/keyfile.json with the actual path # Replace /path/to/your/keyfile.json with the actual path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
# Replace C:\path\to\your\keyfile.json with the actual path # Replace C:\path\to\your\keyfile.json with the actual path
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json" $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json"
``` ```
</TabItem>
</Tabs>
3. [Configure your Google Cloud Project](#set-gcp). 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**. 5. Select **Vertex AI**.
<!-- prettier-ignore -->
> [!WARNING] > [!WARNING]
> Protect your service account key file as it gives access to > Protect your service account key file as it gives access to
> your resources. > 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: 2. Set the `GOOGLE_API_KEY` environment variable:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
# Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
# Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
$env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" $env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
``` ```
</TabItem>
</Tabs>
If you see errors like `"API keys are not supported by this API..."`, your 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 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 <a id="set-gcp"></a> ## Set your Google Cloud project <a id="set-gcp"></a>
<!-- prettier-ignore -->
> [!IMPORTANT] > [!IMPORTANT]
> Most individual Google accounts (free and paid) don't require a > Most individual Google accounts (free and paid) don't require a
> Google Cloud project for authentication. > 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: For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
# Replace YOUR_PROJECT_ID with your actual Google Cloud project ID # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
# Replace YOUR_PROJECT_ID with your actual Google Cloud project ID # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
``` ```
</TabItem>
</Tabs>
To make this setting persistent, see To make this setting persistent, see
[Persisting Environment Variables](#persisting-vars). [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 1. **Add your environment variables to your shell configuration file:** Append
the environment variable commands to your shell's startup file. the environment variable commands to your shell's startup file.
**macOS/Linux** (for example, `~/.bashrc`, `~/.zshrc`, or `~/.profile`): <Tabs>
<TabItem label="macOS/Linux">
```bash (for example, `~/.bashrc`, `~/.zshrc`, or `~/.profile`):
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc
```
**Windows (PowerShell)** (for example, `$PROFILE`): ```bash
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc
```
```powershell </TabItem>
Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' <TabItem label="Windows (PowerShell)">
. $PROFILE
``` (for example, `$PROFILE`):
```powershell
Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"'
. $PROFILE
```
</TabItem>
</Tabs>
<!-- prettier-ignore -->
> [!WARNING] > [!WARNING]
> Be aware that when you export API keys or service account > Be aware that when you export API keys or service account
> paths in your shell configuration file, any process launched from that > 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: Example for user-wide settings:
**macOS/Linux** <Tabs>
<TabItem label="macOS/Linux">
```bash ```bash
mkdir -p ~/.gemini mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF' cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id" GOOGLE_CLOUD_PROJECT="your-project-id"
# Add other variables like GEMINI_API_KEY as needed # Add other variables like GEMINI_API_KEY as needed
EOF EOF
``` ```
**Windows (PowerShell)** </TabItem>
<TabItem label="Windows (PowerShell)">
```powershell ```powershell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini" New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"
@" @"
GOOGLE_CLOUD_PROJECT="your-project-id" GOOGLE_CLOUD_PROJECT="your-project-id"
# Add other variables like GEMINI_API_KEY as needed # Add other variables like GEMINI_API_KEY as needed
"@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append "@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append
``` ```
</TabItem>
</Tabs>
Variables are loaded from the first file found, not merged. Variables are loaded from the first file found, not merged.

5
docs/get-started/index.md
View file

@ -24,7 +24,8 @@ Once Gemini CLI is installed, run Gemini CLI from your command line:
gemini gemini
``` ```
For more installation options, see [Gemini CLI Installation](./installation.md). For more installation options, see
[Gemini CLI Installation](./installation.mdx).
## Authenticate ## 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 Certain account types may require you to configure a Google Cloud project. For
more information, including other authentication methods, see more information, including other authentication methods, see
[Gemini CLI Authentication Setup](./authentication.md). [Gemini CLI Authentication Setup](./authentication.mdx).
## Configure ## Configure

181
docs/get-started/installation.md
View file

@ -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
```

201
docs/get-started/installation.mdx Normal file
View file

@ -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).
<Tabs>
<TabItem label="npm">
Install globally with npm:
```bash
npm install -g @google/gemini-cli
```
</TabItem>
<TabItem label="Homebrew (macOS/Linux)">
Install globally with Homebrew:
```bash
brew install gemini-cli
```
</TabItem>
<TabItem label="MacPorts (macOS)">
Install globally with MacPorts:
```bash
sudo port install gemini-cli
```
</TabItem>
<TabItem label="Anaconda">
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
```
</TabItem>
</Tabs>
## 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:
<Tabs>
<TabItem label="npx">
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
```
</TabItem>
<TabItem label="Docker/Podman Sandbox">
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"
```
</TabItem>
<TabItem label="From source">
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
```
</TabItem>
</Tabs>
## Releases
Gemini CLI has three release channels: stable, preview, and nightly. For most
users, we recommend the stable release, which is the default installation.
<Tabs>
<TabItem label="Stable">
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
```
</TabItem>
<TabItem label="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
```
</TabItem>
<TabItem label="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
```
</TabItem>
</Tabs>

4
docs/index.md
View file

@ -15,9 +15,9 @@ npm install -g @google/gemini-cli
Jump in to Gemini CLI. Jump in to Gemini CLI.
- **[Quickstart](./get-started/index.md):** Your first session with 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. on your system.
- **[Authentication](./get-started/authentication.md):** Setup instructions for - **[Authentication](./get-started/authentication.mdx):** Setup instructions for
personal and enterprise accounts. personal and enterprise accounts.
- **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common - **[CLI cheatsheet](./cli/cli-reference.md):** A quick reference for common
commands and options. commands and options.

4
docs/reference/configuration.md
View file

@ -2079,7 +2079,7 @@ within your user's home folder.
Environment variables are a common way to configure applications, especially for Environment variables are a common way to configure applications, especially for
sensitive information like API keys or for settings that might change between sensitive information like API keys or for settings that might change between
environments. For authentication setup, see the 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. all available authentication methods.
The CLI automatically loads environment variables from an `.env` file. The 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`**: - **`GEMINI_API_KEY`**:
- Your API key for the Gemini API. - Your API key for the Gemini API.
- One of several available - 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 - Set this in your shell profile (for example, `~/.bashrc`, `~/.zshrc`) or an
`.env` file. `.env` file.
- **`GEMINI_MODEL`**: - **`GEMINI_MODEL`**: