Gemini CLI 執行與部署

本文件說明如何執行 Gemini CLI，並解釋 Gemini CLI 採用的部署架構。

執行 Gemini CLI

Gemini CLI 有多種執行方式。您選擇的方式取決於您打算如何使用 Gemini CLI。

這是最推薦給終端使用者安裝 Gemini CLI 的方式。此方法需要從 NPM registry 下載 Gemini CLI 套件。

全域安裝：
```
npm install -g @google/gemini-cli
```
然後，您可以在任何地方執行命令列介面 (Command Line Interface)：
```
gemini
```

NPX 執行:

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

為了安全性與隔離，Gemini CLI 可以在容器中執行。這是 CLI 執行可能產生副作用工具的預設方式。

直接從 Registry 執行： 你可以直接執行已發佈的 sandbox 映像檔。這在僅有 Docker 並想要執行 CLI 的環境中特別有用。
```
# Run the published sandbox image
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
```
使用 --sandbox 旗標 (flag)： 如果你已在本機安裝 Gemini CLI（採用上述標準安裝方式），你可以指示它在 sandbox 容器內執行。
```
gemini --sandbox -y -p "your prompt here"
```

專案貢獻者會希望直接從原始碼執行 Gemini CLI。

開發模式：
此方法提供熱重載（hot-reloading），適合於積極開發時使用。
```
# From the root of the repository
npm run start
```
Production-like mode (Linked package): 此方法會透過連結本地套件來模擬全域安裝。這對於在生產工作流程中測試本地建置特別有用。
```
# 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
```

你可以直接從 GitHub 儲存庫（GitHub repository）執行最新提交的 Gemini CLI 版本。這對於測試仍在開發中的功能非常有用。

# Execute the CLI directly from the main branch on GitHub
npx https://github.com/google-gemini/gemini-cli

上述的執行方式是透過以下架構元件與流程實現的：

NPM 套件

Gemini CLI 專案是一個 monorepo，會將兩個核心套件發佈到 NPM registry：

這些套件會在標準安裝時使用，也會在從原始碼執行 Gemini CLI 時使用。

建置與封裝流程

根據發佈管道，會採用兩種不同的建置流程：

NPM 發佈： 為了發佈到 NPM registry，@google/gemini-cli-core 和 @google/gemini-cli 中的 TypeScript 原始碼會透過 TypeScript Compiler（tsc）轉譯為標準 JavaScript。產生的 dist/ 目錄即為 NPM 套件中發佈的內容。這是 TypeScript 函式庫的標準做法。
GitHub npx 執行： 當直接從 GitHub 執行最新版 Gemini CLI 時，會由 package.json 中的 prepare 腳本觸發不同的流程。此腳本會使用 esbuild，將整個應用程式及其相依套件打包成單一、可自我執行的 JavaScript 檔案。這個 bundle 會在使用者本機即時產生，不會被提交到儲存庫。

Docker sandbox 容器映像檔

基於 Docker 的執行方式由 gemini-cli-sandbox 容器映像檔支援。此映像檔會發佈到容器 registry，並內含已全域安裝的 Gemini CLI 版本。

發佈流程透過 GitHub Actions 自動化。發佈工作流程會執行下列動作：