google-gemini/gemini-cli

Gemini CLI – AI‑powered command‑line assistant

What it is – An open‑source Google‑maintained command‑line tool that lets you talk to the Gemini family of large language models straight from your terminal. It acts as an AI agent that can read, edit, and generate code, run shell commands, fetch web data, and integrate with Google’s Vertex AI and other services.

Key capabilities

• Code understanding & generation – Summarise changes, debug, or create whole applications (even from PDFs, images or sketches) using Gemini’s multimodal models.
• Automation – Query pull‑requests, perform rebases, run scripts, or invoke custom MCP (Model‑Connected‑Program) servers for media generation, Slack messages, database queries, etc.
• Flexible authentication – Supports Google OAuth, a Gemini API key, or Vertex AI credentials for enterprise workloads.
• Scripting & headless mode – Non‑interactive -p flag and JSON/stream‑JSON output make it easy to embed in CI pipelines.
• Extensible tooling – Built‑in file‑system, shell, and web‑fetch tools; custom commands via GEMINI.md; and plug‑in MCP servers for bespoke functionality.
• IDE integration & sandboxing – VS Code companion, token‑caching, checkpointing, and trusted‑folder policies for safe execution.

Installation (choose one)

# One‑off run
npx @google/gemini-cli

# Global npm install
npm install -g @google/gemini-cli

# Homebrew (macOS/Linux)
brew install gemini-cli

Other options include MacPorts and an Anaconda‑based environment for restricted systems.

Getting started

# Launch in the current folder (interactive REPL)
gemini

# Run a single prompt non‑interactively
 gemini -p "Explain the architecture of this codebase"

# Structured output for scripts
 gemini -p "List all functions" --output-format json

You can limit the scope with --include-directories, pick a model with -m gemini-2.5-flash, or stream events with --output-format stream-json.

Authentication options

1. Google OAuth – Sign‑in with your Google account (required for paid Code Assist licenses). Set GOOGLE_CLOUD_PROJECT if needed.
2. Gemini API key – Export GEMINI_API_KEY for direct model selection and usage‑based billing.
3. Vertex AI – Export GOOGLE_API_KEY and set GOOGLE_GENAI_USE_VERTEXAI=true for enterprise‑grade security, higher rate limits, and seamless GCP integration.

Typical workflow

1. Start the REPL – gemini opens an interactive chat that automatically loads the current directory as context.
2. Ask for code – e.g., Write a Discord bot that answers questions using FAQ.md.
3. Iterate – Use slash commands (/help, /chat, /bug) or custom commands defined in GEMINI.md.
4. Automate – Embed calls in CI scripts, using JSON output to parse results programmatically.

Extending the tool

• Add custom commands via the GEMINI.md file.
• Register MCP servers in ~/.gemini/settings.json to expose new tools (Slack, database, etc.).
• Build and share extensions following the docs linked under Custom Extensions.

Community & support

• Open‑source under Apache 2.0; contributions welcomed via pull requests.
• Documentation site: https://www.geminicli.com/docs
• Issue tracker, roadmap, and security policy are all hosted on GitHub.
• A free introductory course is available through DeepLearning.AI.

Status note – Gemini CLI is not optimized for the newest Gemini 4 Argon models; Google recommends using the newer Antigravity CLI for those workloads.