diff --git a/README.md b/README.md index 22e258e289..6e9b1da146 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,9 @@ 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 +See +[Gemini CLI installation, execution, and releases](./docs/get-started/installation.md) +for recommended system specifications and a detailed installation guide. ### Quick Install diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index ef1d6b0ec8..1acf497659 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -1,43 +1,98 @@ -# Gemini CLI installation, execution, and deployment +# Gemini CLI installation, execution, and releases -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. -## How to install and/or run Gemini CLI +## Recommended system specifications -There are several ways to run Gemini CLI. The recommended option depends on how -you intend to use Gemini CLI. +- **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** -- As a standard installation. This is the most straightforward method of using - Gemini CLI. +## 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](/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. -### 1. Standard installation (recommended for standard users) +### Run instantly with npx -This is the recommended way for end-users to install Gemini CLI. It involves -downloading the Gemini CLI package from the NPM registry. +```bash +# Using npx (no installation required) +npx @google/gemini-cli +``` -- **Global install:** +You can also execute the CLI directly from the main branch on GitHub, which is +helpful for testing features still in development: - ```bash - npm install -g @google/gemini-cli - ``` +```bash +npx https://github.com/google-gemini/gemini-cli +``` - Then, run the CLI from anywhere: - - ```bash - gemini - ``` - -- **NPX execution:** - - ```bash - # Execute the latest version from NPM without a global install - npx @google/gemini-cli - ``` - -### 2. Run in a sandbox (Docker/Podman) +### 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. @@ -56,7 +111,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. @@ -79,63 +134,41 @@ code. gemini ``` ---- +## Releases -### 4. Running the latest Gemini CLI commit from GitHub +Gemini CLI has three release channels: nightly, preview, and stable. For most +users, we recommend the stable release, which is the default installation. -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. +### 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 -# Execute the CLI directly from the main branch on GitHub -npx https://github.com/google-gemini/gemini-cli +# Both commands install the latest stable release. +npm install -g @google/gemini-cli +npm install -g @google/gemini-cli@latest ``` -## Deployment architecture +### Preview -The execution methods described above are made possible by the following -architectural components and processes: +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: -**NPM packages** +```bash +npm install -g @google/gemini-cli@preview +``` -Gemini CLI project is a monorepo that publishes two core packages to the NPM -registry: +### Nightly -- `@google/gemini-cli-core`: The backend, handling logic and tool execution. -- `@google/gemini-cli`: The user-facing frontend. +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: -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. +```bash +npm install -g @google/gemini-cli@nightly +```