Skip to content

Gemini CLI 执行和部署

¥Gemini CLI Execution and Deployment

本文档介绍了如何运行 Gemini CLI 并解释了 Gemini CLI 使用的部署架构。

¥This document describes how to run Gemini CLI and explains the deployment architecture that Gemini CLI uses.

运行 Gemini CLI

¥Running Gemini CLI

有几种方法可以运行 Gemini CLI。具体选择哪种方式取决于您打算如何使用 Gemini CLI。

¥There are several ways to run Gemini CLI. The option you choose depends on how you intend to use Gemini CLI.

¥1. Standard installation (Recommended for typical users)

这是推荐最终用户安装 Gemini CLI 的方式。它涉及从 NPM 注册表下载 Gemini CLI 包。

¥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

¥bash npm install -g @google/gemini-cli

然后，从任何地方运行 CLI：

¥Then, run the CLI from anywhere:

bash gemini

¥bash gemini

  • NPX 执行：

    ¥NPX execution:

bash # Execute the latest version from NPM without a global install npx @google/gemini-cli

¥bash # Execute the latest version from NPM without a global install npx @google/gemini-cli

2. 在沙盒中运行（Docker/Podman）

¥2. Running in a sandbox (Docker/Podman)

为了安全和隔离，Gemini CLI 可以在容器内运行。这是 CLI 执行可能产生副作用的工具的默认方式。

¥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.

  • 直接从注册表获取：您可以直接运行已发布的沙盒镜像。这对于只有 Docker 且想要运行 CLI 的环境非常有用。bash # Run the published sandbox image docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

    ¥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

  • 使用--sandbox旗帜：如果您已在本地安装了 Gemini CLI（使用上面描述的标准安装），则可以指示它在沙盒容器内运行。bash gemini --sandbox -y -p "your prompt here"

    ¥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. Running from source (Recommended for Gemini CLI contributors)

项目贡献者希望直接从源代码运行 CLI。

¥Contributors to the project will want to run the CLI directly from the source code.

  • 开发模式：此方法提供热重加载，对于主动开发很有用。bash # From the root of the repository npm run start

    ¥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 # 将本地 cli 包链接到全局 node_modules npm link packages/cli

¥```bash # Link the local cli package to your global node_modules npm link packages/cli

# 现在您可以使用gemini命令双子座```

¥# Now you can run your local version using the gemini command gemini ```

4. 从 GitHub 运行最新的 Gemini CLI 提交

¥4. Running the latest Gemini CLI commit from GitHub

您可以直接从 GitHub 仓库运行最新提交的 Gemini CLI 版本。这对于测试仍在开发中的功能非常有用。

¥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.

# 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 包

¥NPM packages

Gemini CLI 项目是一个 monorepo，它将两个核心包发布到 NPM 注册表：

¥Gemini CLI project is a monorepo that publishes two core packages to the NPM registry:

  • @google/gemini-cli-core：后端，处理逻辑和工具执行。

    ¥@google/gemini-cli-core: The backend, handling logic and tool execution.

  • @google/gemini-cli：面向用户的前端。

    ¥@google/gemini-cli: The user-facing frontend.

执行标准安装时以及从源运行 Gemini CLI 时使用这些包。

¥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 出版物：为了发布到 NPM 注册表，TypeScript 源代码位于@google/gemini-cli-core和@google/gemini-cli使用 TypeScript 编译器将其转换为标准 JavaScript（tsc）结果dist/目录是 NPM 包中发布的目录。这是 TypeScript 库的标准方法。

    ¥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.

  • GitHubnpx执行：直接从 GitHub 运行最新版本的 Gemini CLI 时，会触发不同的进程prepare脚本package.json.此脚本使用esbuild将整个应用程序及其依赖项打包成一个独立的 JavaScript 文件。此打包文件在用户的计算机上即时创建，不会签入到代码库中。

    ¥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 沙盒镜像

¥Docker sandbox image

基于 Docker 的执行方法由gemini-cli-sandbox容器镜像。此镜像已发布到容器注册表，并包含预安装的 Gemini CLI 全局版本。

¥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

发布过程通过 GitHub Actions 自动执行。发布工作流执行以下操作：

¥The release process is automated through GitHub Actions. The release workflow performs the following actions:

  1. 使用以下方式构建 NPM 包tsc。

    ¥Build the NPM packages using tsc.

  2. 将 NPM 包发布到工件注册表。

    ¥Publish the NPM packages to the artifact registry.

  3. 使用捆绑资产创建 GitHub 版本。

    ¥Create GitHub releases with bundled assets.