From af1436cea18cf7b90b78a875cc60b596b0606893 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Thu, 26 Mar 2026 09:42:42 -0700 Subject: [PATCH] Test mdx file --- docs/get-started/index.md | 2 +- docs/get-started/installation.mdx | 157 ++++++++++++++++++++++++++++++ docs/index.md | 2 +- 3 files changed, 159 insertions(+), 2 deletions(-) create mode 100644 docs/get-started/installation.mdx diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 9cdb9f63a1..d51d89aec5 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -24,7 +24,7 @@ Once Gemini CLI is installed, run Gemini CLI from your command line: gemini ``` -For more installation options, see [Gemini CLI Installation](./installation). +For more installation options, see [Gemini CLI Installation](./installation/). ## Authenticate diff --git a/docs/get-started/installation.mdx b/docs/get-started/installation.mdx new file mode 100644 index 0000000000..edb3fb2794 --- /dev/null +++ b/docs/get-started/installation.mdx @@ -0,0 +1,157 @@ +# 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: + + + + Install globally with npm: + + ```bash + npm install -g @google/gemini-cli + ``` + + + Install globally with Homebrew (macOS/Linux): + + ```bash + brew install gemini-cli + ``` + + + +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). + +## 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:latest + ``` +- **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 6406ad7aaa..6377aebc54 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ 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):** How to install Gemini CLI on +- **[Installation](./get-started/installation/):** How to install Gemini CLI on your system. - **[Authentication](./get-started/authentication.md):** Setup instructions for personal and enterprise accounts.