本文档描述了如何运行 Gemini CLI 并解释了 Gemini CLI 使用的部署架构。
运行 Gemini CLI
有几种方式可以运行 Gemini CLI。您选择的选项取决于您打算如何使用 Gemini CLI。
1. 标准安装（推荐给典型用户）
这是推荐给最终用户安装 Gemini CLI 的方式。它涉及从 NPM 注册表下载 Gemini CLI 包。
全局安装：
# 全局安装 CLI
npm install -g @google/gemini-cli
# 现在您可以从任何地方运行 CLI
geminiNPX 执行：
# 无需全局安装即可从 NPM 执行最新版本
npx @google/gemini-cli2. 在沙盒中运行（Docker/Podman）
为了安全和隔离，Gemini CLI 可以在容器内运行。这是 CLI 执行可能有副作用的工具时的默认方式。
直接从注册表运行：
您可以直接运行发布的沙盒镜像。这对于只有 Docker 并想要运行 CLI 的环境很有用。
# 运行发布的沙盒镜像
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1使用 --sandbox 标志：
如果您已经在本地安装了 Gemini CLI（使用上面描述的标准安装），您可以指示它在沙盒容器内运行。
gemini --sandbox "your prompt here"3. 从源代码运行（推荐给 Gemini CLI 贡献者）
项目贡献者会希望直接从源代码运行 CLI。
开发模式：
这种方法提供热重载，对于活跃开发很有用。
# 从仓库根目录
npm run start生产模式（链接包）：
这种方法通过链接您的本地包来模拟全局安装。它对于在生产工作流中测试本地构建很有用。
# 将本地 CLI 包链接到您的全局 node_modules
npm link packages/cli
# 现在您可以使用 `gemini` 命令运行您的本地版本
gemini4. 从 GitHub 运行最新的 Gemini CLI 提交
您可以直接从 GitHub 仓库运行最新提交的 Gemini CLI 版本。这对于测试仍在开发中的功能很有用。
# 直接从 GitHub 主分支执行 CLI
npx https://github.com/google-gemini/gemini-cli部署架构
上述描述的执行方法通过以下架构组件和流程实现：
NPM 包
Gemini CLI 项目是一个 monorepo，向 NPM 注册表发布两个核心包：
@google/gemini-cli-core：后端，处理逻辑和工具执行。@google/gemini-cli：面向用户的前端。
这些包在执行标准安装和从源代码运行 Gemini CLI 时使用。
构建和打包流程
有两个不同的构建过程，取决于分发渠道：
NPM 发布：
对于发布到 NPM 注册表，@google/gemini-cli-core 和 @google/gemini-cli 中的 TypeScript 源代码使用 TypeScript 编译器（tsc）转译为标准 JavaScript。生成的 dist/ 目录是在 NPM 包中发布的内容。这是 TypeScript 库的标准方法。
GitHub npx 执行：
当直接从 GitHub 运行最新版本的 Gemini CLI 时，package.json 中的 prepare 脚本触发不同的过程。这个脚本使用 esbuild 将整个应用程序及其依赖项打包成一个自包含的 JavaScript 文件。这个包在用户的机器上即时创建，并且不检入仓库。
Docker 沙盒镜像
基于 Docker 的执行方法由
gemini-cli-sandbox 容器镜像支持。这个镜像发布到容器注册表，包含预安装的全局版本 Gemini CLI。scripts/prepare-cli-packagejson.js 脚本在发布前动态将此镜像的 URI 注入到 CLI 的 package.json 中，因此 CLI 知道在使用 --sandbox 标志时要拉取哪个镜像。
发布流程
统一脚本 npm run publish:release 编排发布流程。该脚本执行以下操作：
发布步骤：
- 使用
tsc构建 NPM 包。 - 使用 Docker 镜像 URI 更新 CLI 的
package.json。 - 构建并标记
gemini-cli-sandboxDocker 镜像。 - 将 Docker 镜像推送到容器注册表。
- 将 NPM 包发布到制品注册表。