Gemini CLI

Which Google CLI do you need?

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

Install globally with npm

Install globally with Homebrew (macOS/Linux)

Install globally with MacPorts (macOS)

Install with Anaconda (for restricted environments)

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.

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.

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.

📋 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

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

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

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

🚀 Getting Started

Basic Usage

Start in current directory

Include multiple directories

Use specific model

Non-interactive mode for scripts

Get a simple text response:

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

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

Quick Examples

Start a new project

Analyze existing code

📚 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:

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

Built with ❤️ by Google and the open source community