From 105935b661901315125ddd0e129ba56e67924ed8 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 08:20:15 -0800 Subject: [PATCH 01/10] Update installation guide. --- docs/get-started/installation.md | 73 +++++++++----------------------- 1 file changed, 19 insertions(+), 54 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index ef1d6b0ec83..d7f11fc865b 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -1,7 +1,23 @@ # Gemini CLI installation, execution, and deployment -Install and run Gemini CLI. This document provides an overview of Gemini CLI's -installation methods and deployment architecture. +This document provides an overview of Gemini CLI's sytem requriements, +installation methods, and release types. + +## System requirements + +- **Operating System:** + - macOS 16+ + - Windows 10.0.26100+ + - Ubuntu 20.04+ +- **Runtime:** Node.js 20.0.0+ +- **Shell:** Bash or Zsh recommended +- **Location:** + [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) +- **Internet connection required** + +Gemini CLI comes pre-installed on +[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and +[**Cloud Workstations**](https://cloud.google.com/workstations). ## How to install and/or run Gemini CLI @@ -13,7 +29,7 @@ you intend to use Gemini CLI. - In a sandbox. This method offers increased security and isolation. - From the source. This is recommended for contributors to the project. -### 1. Standard installation (recommended for standard users) +### 1. Standard installation (recommended for most users) This is the recommended way for end-users to install Gemini CLI. It involves downloading the Gemini CLI package from the NPM registry. @@ -79,8 +95,6 @@ code. gemini ``` ---- - ### 4. Running the latest Gemini CLI commit from GitHub You can run the most recently committed version of Gemini CLI directly from the @@ -90,52 +104,3 @@ GitHub repository. This is useful for testing features still in development. # Execute the CLI directly from the main branch on GitHub npx https://github.com/google-gemini/gemini-cli ``` - -## Deployment architecture - -The execution methods described above are made possible by the following -architectural components and processes: - -**NPM packages** - -Gemini CLI project is a monorepo that publishes two core packages to the NPM -registry: - -- `@google/gemini-cli-core`: The backend, handling logic and tool execution. -- `@google/gemini-cli`: The user-facing frontend. - -These packages are used when performing the standard installation and when -running Gemini CLI from the source. - -**Build and packaging processes** - -There are two distinct build processes used, depending on the distribution -channel: - -- **NPM publication:** For publishing to the NPM registry, the TypeScript source - code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into - standard JavaScript using the TypeScript Compiler (`tsc`). The resulting - `dist/` directory is what gets published in the NPM package. This is a - standard approach for TypeScript libraries. - -- **GitHub `npx` execution:** When running the latest version of Gemini CLI - directly from GitHub, a different process is triggered by the `prepare` script - in `package.json`. This script uses `esbuild` to bundle the entire application - and its dependencies into a single, self-contained JavaScript file. This - bundle is created on-the-fly on the user's machine and is not checked into the - repository. - -**Docker sandbox image** - -The Docker-based execution method is supported by the `gemini-cli-sandbox` -container image. This image is published to a container registry and contains a -pre-installed, global version of Gemini CLI. - -## Release process - -The release process is automated through GitHub Actions. The release workflow -performs the following actions: - -1. Build the NPM packages using `tsc`. -2. Publish the NPM packages to the artifact registry. -3. Create GitHub releases with bundled assets. From 03f5836fc6f8c8c1239a97d0b702099745c0b068 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 12:11:00 -0800 Subject: [PATCH 02/10] Update system specs. --- docs/get-started/installation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index d7f11fc865b..e1d14aaa9f6 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -3,22 +3,18 @@ This document provides an overview of Gemini CLI's sytem requriements, installation methods, and release types. -## System requirements +## Recommended system specifications - **Operating System:** - - macOS 16+ - - Windows 10.0.26100+ + - macOS 26+ + - Windows 11 24H2+ - Ubuntu 20.04+ - **Runtime:** Node.js 20.0.0+ -- **Shell:** Bash or Zsh recommended +- **Shell:** Bash or Zsh - **Location:** [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) - **Internet connection required** -Gemini CLI comes pre-installed on -[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and -[**Cloud Workstations**](https://cloud.google.com/workstations). - ## How to install and/or run Gemini CLI There are several ways to run Gemini CLI. The recommended option depends on how @@ -29,6 +25,10 @@ you intend to use Gemini CLI. - In a sandbox. This method offers increased security and isolation. - From the source. This is recommended for contributors to the project. +Gemini CLI comes pre-installed on +[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and +[**Cloud Workstations**](https://cloud.google.com/workstations). + ### 1. Standard installation (recommended for most users) This is the recommended way for end-users to install Gemini CLI. It involves From ef6962e40324ec3d7569bb339b4a413528bd91e3 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 12:19:47 -0800 Subject: [PATCH 03/10] Add hardware suggestions. --- docs/get-started/installation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index e1d14aaa9f6..8ae90d1a68f 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -9,6 +9,9 @@ installation methods, and release types. - macOS 26+ - Windows 11 24H2+ - Ubuntu 20.04+ +- **Hardware:** + - "Casual" use (short sessions, asking questions, small edits): 4GB+ RAM + - "Power" use (long sessions, large codebases, deep context): 16GB+ RAM - **Runtime:** Node.js 20.0.0+ - **Shell:** Bash or Zsh - **Location:** From 1c43613908206c535f827302e0b430076f0c51db Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 12:20:51 -0800 Subject: [PATCH 04/10] Adjust hardware info. --- docs/get-started/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 8ae90d1a68f..ef47f72b59d 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -10,8 +10,8 @@ installation methods, and release types. - Windows 11 24H2+ - Ubuntu 20.04+ - **Hardware:** - - "Casual" use (short sessions, asking questions, small edits): 4GB+ RAM - - "Power" use (long sessions, large codebases, deep context): 16GB+ RAM + - "Casual" usage: 4GB+ RAM (short sessions, asking questions, small edits) + - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context) - **Runtime:** Node.js 20.0.0+ - **Shell:** Bash or Zsh - **Location:** From 9a7c4c3b8ae41fa3d06e1729f64ba467a2bb5480 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 18:07:59 -0800 Subject: [PATCH 05/10] Update installation guide and README --- README.md | 18 ++++- docs/get-started/installation.md | 122 +++++++++++++++++++++++-------- 2 files changed, 104 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 22e258e2896..caf88e28953 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,20 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/). ## 📦 Installation -### Pre-requisites before installation - -- Node.js version 20 or higher -- macOS, Linux, or Windows +### Recommended System Specifications + +- **Operating System:** + - macOS 26+ + - 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 or Zsh +- **Location:** + [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) +- **Internet connection required** ### Quick Install diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index ef47f72b59d..f9a92b52626 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -10,7 +10,7 @@ installation methods, and release types. - Windows 11 24H2+ - Ubuntu 20.04+ - **Hardware:** - - "Casual" usage: 4GB+ RAM (short sessions, asking questions, small edits) + - "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 or Zsh @@ -18,45 +18,74 @@ installation methods, and release types. [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) - **Internet connection required** -## How to install and/or run Gemini CLI +## Install Gemini CLI -There are several ways to run Gemini CLI. The recommended option depends on how -you intend to use Gemini CLI. +We recommend most users install Gemini CLI using one of the following +installation methods: -- As a standard installation. This is the most straightforward method of using - Gemini CLI. -- In a sandbox. This method offers increased security and isolation. -- From the source. This is recommended for contributors to the project. +- npm +- Homebrew +- MacPorts +- Anaconda -Gemini CLI comes pre-installed on +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). -### 1. Standard installation (recommended for most users) +### Install globally with npm -This is the recommended way for end-users to install Gemini CLI. It involves -downloading the Gemini CLI package from the NPM registry. +```bash +npm install -g @google/gemini-cli +``` -- **Global install:** +### Install globally with Homebrew (macOS/Linux) - ```bash - npm install -g @google/gemini-cli - ``` +```bash +brew install gemini-cli +``` - Then, run the CLI from anywhere: +### Install globally with MacPorts (macOS) - ```bash - gemini - ``` +```bash +sudo port install gemini-cli +``` -- **NPX execution:** +### Install with Anaconda (for restricted environments) - ```bash - # Execute the latest version from NPM without a global install - npx @google/gemini-cli - ``` +```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](/docs/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. -### 2. Run in a sandbox (Docker/Podman) +### Run instantly with npx + +```bash +# Using npx (no installation required) +npx @google/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. @@ -75,7 +104,7 @@ the default way that the CLI executes tools that might have side effects. gemini --sandbox -y -p "your prompt here" ``` -### 3. Run from source (recommended for Gemini CLI contributors) +### Run from source (recommended for Gemini CLI contributors) Contributors to the project will want to run the CLI directly from the source code. @@ -98,12 +127,41 @@ code. gemini ``` -### 4. Running the latest Gemini CLI commit from GitHub +## 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 -You can run the most recently committed version of Gemini CLI directly from the -GitHub repository. This is useful for testing features still in development. +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 `nightly` tag: ```bash -# Execute the CLI directly from the main branch on GitHub -npx https://github.com/google-gemini/gemini-cli +npm install -g @google/gemini-cli@nightly ``` From 5a17e7f3a02013381f6f5c828d9c92c916e08cba Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 18:08:53 -0800 Subject: [PATCH 06/10] Fix typo. --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index f9a92b52626..242aed24e2c 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -160,7 +160,7 @@ 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 `nightly` tag: +installing with the `nightly` tag: ```bash npm install -g @google/gemini-cli@nightly From c9e84a69be1ed98f79e6e427272c90ff969da6cb Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Wed, 11 Feb 2026 18:10:19 -0800 Subject: [PATCH 07/10] Fix macOS version. --- README.md | 2 +- docs/get-started/installation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index caf88e28953..2580f2fefa7 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/). ### Recommended System Specifications - **Operating System:** - - macOS 26+ + - macOS 15+ - Windows 11 24H2+ - Ubuntu 20.04+ - **Hardware:** diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 242aed24e2c..c5c2f64f188 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -6,7 +6,7 @@ installation methods, and release types. ## Recommended system specifications - **Operating System:** - - macOS 26+ + - macOS 15+ - Windows 11 24H2+ - Ubuntu 20.04+ - **Hardware:** From 2d38b75148fdd473ffeeb06737cd38b20ccc38b6 Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Thu, 12 Feb 2026 11:01:04 -0800 Subject: [PATCH 08/10] Update installation.md --- docs/get-started/installation.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index c5c2f64f188..1acf4976594 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -1,4 +1,4 @@ -# Gemini CLI installation, execution, and deployment +# Gemini CLI installation, execution, and releases This document provides an overview of Gemini CLI's sytem requriements, installation methods, and release types. @@ -85,6 +85,13 @@ You can also run Gemini CLI using one of the following advanced methods: 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 From 5f71640db7167595a89bc0921893315fb7a44a99 Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Thu, 12 Feb 2026 14:53:39 -0800 Subject: [PATCH 09/10] Update README.md --- README.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2580f2fefa7..82e063ce040 100644 --- a/README.md +++ b/README.md @@ -29,20 +29,8 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/). ## 📦 Installation -### 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 or Zsh -- **Location:** - [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) -- **Internet connection required** +See [Gemini CLI installation, execution, and releases](./docs/get-started/installation.md) +for recommended system specifications and a detailed installation guide. ### Quick Install From 82a1ad2b5e6cadd237f36f9d786ce49317bb04ee Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Thu, 12 Feb 2026 15:54:08 -0800 Subject: [PATCH 10/10] Foramt readme. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 82e063ce040..6e9b1da1467 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,8 @@ Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/). ## 📦 Installation -See [Gemini CLI installation, execution, and releases](./docs/get-started/installation.md) +See +[Gemini CLI installation, execution, and releases](./docs/get-started/installation.md) for recommended system specifications and a detailed installation guide. ### Quick Install