gemini-cli

Gemini CLI

[!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?

Tool	Best for	Links
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

• Quickstart Guide - Get up and running quickly.
• Authentication Setup - Detailed auth configuration.
• Configuration Guide - Settings and customization.
• Keyboard Shortcuts - Productivity tips.

Core Features

• Commands Reference - All slash commands (/help, /chat, etc).
• Custom Commands - Create your own reusable commands.
• Context Files (GEMINI.md) - Provide persistent context to Gemini CLI.
• Checkpointing - Save and resume conversations.
• Token Caching - Optimize token usage.

Tools & Extensions

• Built-in Tools Overview
  • File System Operations
  • Shell Commands
  • Web Fetch & Search
• MCP Server Integration - Extend with custom tools.
• Custom Extensions - Build and share your own commands.

Advanced Topics

• Headless Mode (Scripting) - Use Gemini CLI in automated workflows.
• IDE Integration - VS Code companion.
• Sandboxing & Security - Safe execution environments.
• Trusted Folders - Control execution policies by folder.
• Enterprise Guide - Deploy and manage in a corporate environment.
• Telemetry & Monitoring - Usage tracking.
• Tools reference - Built-in tools overview.
• Local development - Local development tooling.

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

• Free Course - Learn the basics.
• Official Roadmap - See what's coming next.
• Changelog - See recent notable updates.
• NPM Package - Package registry.
• GitHub Issues - Report bugs or request features.
• Security Advisories - Security updates.

Uninstall

See the Uninstall Guide for removal instructions.

📄 Legal

• License: Apache License 2.0
• Terms of Service: Terms & Privacy
• Security: Security Policy

---