diff --git a/docs/get-started/deployment.md b/docs/get-started/deployment.md index 1ea278ccc4..21ab52e32a 100644 --- a/docs/get-started/deployment.md +++ b/docs/get-started/deployment.md @@ -1,10 +1,13 @@ -# Gemini CLI Execution and Deployment +Note: This page will be replaced by [installation.md](installation.md). -This document describes how to run Gemini CLI and its deployment architecture. +# Gemini CLI Installation, Execution, and Deployment -## Running Gemini CLI +Install and run Gemini CLI. This document provides an overview of Gemini CLI's +installation methods and deployment architecture. -There are several ways to run Gemini CLI. The option you choose depends on how +## How to install and/or run Gemini CLI + +There are several ways to run Gemini CLI. The recommended option depends on how you intend to use Gemini CLI. - As a standard installation. This is the most straightforward method of using diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 6f1b059630..3f7657307a 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -24,8 +24,7 @@ Once Gemini CLI is installed, run Gemini CLI from your command line: gemini ``` -For more deployment options, see -[Gemini CLI Execution and Deployment](./deployment.md). +For more installation options, see [Gemini CLI Installation](./installation.md). ## Authenticate diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md new file mode 100644 index 0000000000..b7b7cb9077 --- /dev/null +++ b/docs/get-started/installation.md @@ -0,0 +1,141 @@ +# 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. + +## How to install and/or run Gemini CLI + +There are several ways to run Gemini CLI. The recommended option depends on how +you intend to use Gemini CLI. + +- 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. + +### 1. Standard installation (recommended for standard users) + +This is the recommended way for end-users to install Gemini CLI. It involves +downloading the Gemini CLI package from the NPM registry. + +- **Global install:** + + ```bash + npm install -g @google/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) + +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" + ``` + +### 3. 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 + ``` + +--- + +### 4. Running the latest Gemini CLI commit from GitHub + +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. + +```bash +# 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. diff --git a/docs/index.md b/docs/index.md index 2d817836cf..55b2267ad1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ This documentation is organized into the following sections: - **[Gemini CLI Quickstart](./get-started/index.md):** Let's get started with Gemini CLI. -- **[Deployment](./get-started/deployment.md):** Install and run Gemini CLI. +- **[Installation](./get-started/installation.md):** Install and run Gemini CLI. - **[Authentication](./get-started/authentication.md):** Authenticate Gemini CLI. - **[Configuration](./get-started/configuration.md):** Information on @@ -73,6 +73,8 @@ This documentation is organized into the following sections: - **[Extensions](./extensions/index.md):** How to extend the CLI with new functionality. +- **[Get Started with Extensions](./extensions/getting-started-extensions.md):** + Learn how to build your own extension. - **[Extension Releasing](./extensions/extension-releasing.md):** How to release Gemini CLI extensions. diff --git a/docs/sidebar.json b/docs/sidebar.json index 0430acdabb..cc9146cfc3 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -28,8 +28,8 @@ "slug": "docs/get-started/configuration" }, { - "label": "Deployment", - "slug": "docs/get-started/deployment" + "label": "Installation", + "slug": "docs/get-started/installation" }, { "label": "Examples", @@ -159,6 +159,10 @@ "label": "Introduction", "slug": "docs/extensions" }, + { + "label": "Get Started with Extensions", + "slug": "docs/extensions/getting-started-extensions.md" + }, { "label": "Extension Releasing", "slug": "docs/extensions/extension-releasing" @@ -189,6 +193,10 @@ "label": "Releases", "slug": "docs/releases" }, + { + "label": "Changelog", + "slug": "docs/changelogs" + }, { "label": "Integration Tests", "slug": "docs/integration-tests"