@google/gemini-cli

中文文档
0.68.0发布于 2026/11/11Apache-2.0ES Module零依赖近 30 天下载 178.9万

Gemini CLI

原始使用文档
文档目录27 节
  1. 📦 Installation
  2. Quick Install
  3. Release Channels
  4. Preview
  5. Stable
  6. Nightly
  7. 📋 Key Features
  8. Code Understanding & Generation
  9. Automation & Integration
  10. 🔐 Authentication Options
  11. Option 1: Sign in with Google (OAuth login using your Googl…
  12. Option 2: Gemini API Key
  13. Option 3: Vertex AI
  14. 🚀 Getting Started
  15. Basic Usage
  16. Quick Examples
  17. 📚 Documentation
  18. Getting Started
  19. Core Features
  20. Tools & Extensions
  21. Advanced Topics
  22. Troubleshooting & Support
  23. Using MCP Servers
  24. 🤝 Contributing
  25. 📖 Resources
  26. Uninstall
  27. 📄 Legal

Gemini CLI

Gemini CLI CI Gemini CLI E2E (Chained) Version License View Code Wiki

[!IMPORTANT] Read before installing — Gemini CLI status & tool guide

  • Enterprise Code Assist only: Designed for Gemini Code Assist Standard / Enterprise licenses and Code Assist for GitHub on Google Cloud (your access remains unchanged).
  • No free tier or Google AI plans: Free individual access and Google AI Pro / Ultra (Google One) moved to Antigravity CLI on June 18, 2026 (transition post).
  • Not optimized for Gemini 4+: Not tuned for the Gemini 4 series (for example, Gemini 4 Argon) or future releases in this or later generations.
  • Not for model benchmarks: Don't use Gemini CLI to benchmark Gemini models—its harness isn't tuned for Gemini 4+ and produces unrepresentative scores.

Which Google CLI do you need?

ToolBest forLinks
Antigravity CLI (agy)Interactive multi-agent coding terminal. Use for Gemini 4 Argon+, free / Google AI Pro & Ultra accounts, or Google Cloud.Download · Migrate · Argon post
Gemini API CLI (gemini-api)Stateless API CLI (not a coding harness). Gives agents (agy, Claude Code, Codex), scripts, and CI direct commands for Gemini models, media gen, file analysis, and managed agents.GitHub · Releases · API docs
Gemini CLI (gemini, this repo)Organizations with Gemini Code Assist Standard / Enterprise or Code Assist for GitHub on Google Cloud (plus legacy paid API / Vertex keys).Docs

Gemini CLI (gemini) is an open-source terminal agent maintained for enterprise Gemini Code Assist workflows on Google Cloud. Learn more in the Gemini CLI documentation.

📦 Installation

See Gemini CLI installation, execution, and releases for recommended system specifications and a detailed installation guide.

Quick Install

Run instantly with npx

# Using npx (no installation required)
npx @google/gemini-cli

Install globally with npm

npm install -g @google/gemini-cli

Install globally with Homebrew (macOS/Linux)

brew install gemini-cli

Install globally with MacPorts (macOS)

sudo port install gemini-cli

Install with Anaconda (for restricted environments)

# 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

Release Channels

See Releases for more details.

Preview

New preview releases will be published each week at UTC 23:59 on Tuesdays. These releases will not have been fully vetted and may contain regressions or other outstanding issues. Please help us test and install with preview tag.

npm install -g @google/gemini-cli@preview

Stable

  • New stable releases will be published each week at UTC 20:00 on Tuesdays, this will be the full promotion of last week's preview release + any bug fixes and validations. Use latest tag.
npm install -g @google/gemini-cli@latest

Nightly

  • New releases will be published each day at UTC 00:00. This will be all changes from the main branch as represented at time of release. It should be assumed there are pending validations and issues. Use nightly tag.
npm install -g @google/gemini-cli@nightly

📋 Key Features

Code Understanding & Generation

  • Query and edit large codebases
  • Generate new apps from PDFs, images, or sketches using multimodal capabilities
  • Debug issues and troubleshoot with natural language

Automation & Integration

  • Automate operational tasks like querying pull requests or handling complex rebases
  • Use MCP servers to connect new capabilities, including media generation with Imagen, Veo or Lyria
  • Run non-interactively in scripts for workflow automation

🔐 Authentication Options

Choose the authentication method that best fits your needs:

Option 1: Sign in with Google (OAuth login using your Google Account)

When using a paid Code Assist License from your organization, remember to set the Google Cloud Project

# Set your Google Cloud Project
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

Option 2: Gemini API Key

✨ Best for: Developers who need specific model control or paid tier access

Benefits:

  • Model selection: Choose specific Gemini models
  • Usage-based billing: Upgrade for higher limits when needed
# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Option 3: Vertex AI

✨ Best for: Enterprise teams and production workloads

Benefits:

  • Enterprise features: Advanced security and compliance
  • Scalable: Higher rate limits with billing account
  • Integration: Works with existing Google Cloud infrastructure
# Get your key from Google Cloud Console
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

For Google Workspace accounts and other authentication methods, see the authentication guide.

🚀 Getting Started

Basic Usage

Start in current directory

gemini

Include multiple directories

gemini --include-directories ../lib,../docs

Use specific model

gemini -m gemini-2.5-flash

Non-interactive mode for scripts

Get a simple text response:

gemini -p "Explain the architecture of this codebase"

For more advanced scripting, including how to parse JSON and handle errors, use the --output-format json flag to get structured output:

gemini -p "Explain the architecture of this codebase" --output-format json

For real-time event streaming (useful for monitoring long-running operations), use --output-format stream-json to get newline-delimited JSON events:

gemini -p "Run tests and deploy" --output-format stream-json

Quick Examples

Start a new project

cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file I will provide

Analyze existing code

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

📚 Documentation

Getting Started

Core Features

Tools & Extensions

Advanced Topics

Troubleshooting & Support

  • Troubleshooting Guide - Common issues and solutions.
  • FAQ - Frequently asked questions.
  • Use /bug command to report issues directly from the CLI.

Using MCP Servers

Configure MCP servers in ~/.gemini/settings.json to extend Gemini CLI with custom tools:

> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users

See the MCP Server Integration guide for setup instructions.

🤝 Contributing

We welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we encourage the community to:

  • Report bugs and suggest features.
  • Improve documentation.
  • Submit code improvements.
  • Share your MCP servers and extensions.

See our Contributing Guide for development setup, coding standards, and how to submit pull requests.

Check our Official Roadmap for planned features and priorities.

📖 Resources

Uninstall

See the Uninstall Guide for removal instructions.

Star History Rank


Built with ❤️ by Google and the open source community

版本与发布记录

@google/gemini-cli 共发布 810 个版本,首次发布于 2025/06/25;过去 12 个月发布了 526 个版本。

版本发布日期距今
0.68.0latest2026/11/115 天前
0.69.0-preview.0preview2026/11/115 天前
0.67.02026/11/0511 天前
0.68.0-preview.02026/11/0512 天前
0.67.0-nightly.20261104.g89e9d25d6nightly2026/11/0412 天前
0.67.0-nightly.20261103.g0ac57c0292026/11/0313 天前

其他发布通道:false → 0.42.0-nightly.20260512.g11a9edc80,nightly → 0.67.0-nightly.20261104.g89e9d25d6,preview → 0.69.0-preview.0。

关于 @google/gemini-cli 的常见问题

@google/gemini-cli 是什么?

Gemini CLI

如何安装 @google/gemini-cli?

在项目目录运行 npm install @google/gemini-cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gemini,可以用 npx gemini 直接运行。

@google/gemini-cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/google__gemini-cli 是否存在。

@google/gemini-cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@google/gemini-cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@google/gemini-cli 可以商用吗?

@google/gemini-cli 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@google/gemini-cli 的下载量有多少?

根据 npm 官方下载统计,@google/gemini-cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 1,789,160 次,日均约 59,639 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@google/gemini-cli 还在维护吗?

最新版本 0.68.0 发布于 2026/11/11(5 天前);至今共发布 810 个版本,其中过去 12 个月发布了 526 个;首次发布于 2025/06/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。