Command Palette

Search for a command to run...

GitHubGitHub

Gemini CLI Installation Guide

Install Google's Gemini CLI with npm, npx or Homebrew, authenticate with OAuth, an API key or Vertex AI, script it in headless mode and migrate to Antigravity CLI.

Gemini CLI is Google's open-source terminal agent (Apache 2.0). It ships weekly releases with a preview, stable and nightly channel.

System Requirements

  • Node.js 20 or newer (22+ recommended)
  • A Google account, a Gemini API key, or a Google Cloud project with Vertex AI enabled
  • macOS, Linux or Windows (WSL2 recommended on Windows)

Installation Instructions

# Run it without installing anything
npx @google/gemini-cli
 
# Install globally with npm
npm install -g @google/gemini-cli
 
# Install with Homebrew (macOS and Linux)
brew install gemini-cli
# macOS with MacPorts
sudo port install gemini-cli
# In a Conda environment (restricted networks)
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

Release Channels

# Stable — the full promotion of last week's preview release
npm install -g @google/gemini-cli@latest
 
# Preview — published every Tuesday at 23:59 UTC
npm install -g @google/gemini-cli@preview
 
# Nightly — every change from main, published daily
npm install -g @google/gemini-cli@nightly

Migrating to Antigravity CLI

# Download Antigravity CLI
# https://antigravity.google/download
 
# The migration guide
# https://antigravity.google/docs/gcli-migration

Antigravity CLI is written in Go, so it is faster, and it keeps the parts people relied on most: Agent Skills, hooks, subagents and extensions (now Antigravity plugins). The migration guide covers moving your settings, MCP servers and provider configuration.

Authentication

Sign in with Google

# Interactive OAuth login
gemini
 
# Or set the project for a paid Code Assist licence
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

Gemini API Key

# Get a key at https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Vertex AI

# For enterprise use and higher rate limits
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Using the CLI

# Start an interactive session in the current directory
gemini
 
# Include more directories in the context
gemini --include-directories ../lib,../docs
 
# Pick a model
gemini -m gemini-2.5-flash

Headless and Scripting Mode

# A simple text response
gemini -p "Explain the architecture of this codebase"
 
# Structured output
gemini -p "Explain the architecture of this codebase" --output-format json
 
# Stream events for long-running operations
gemini -p "Run the tests and deploy" --output-format stream-json

Project Context

Create a GEMINI.md in the project root to give the agent persistent context. Commit it so the whole team shares the same instructions:

# GEMINI.md
 
- Run `npm run lint && npm test` before reporting a change as done.
- Never edit files under `migrations/` without asking first.
- Use the repository pattern in `src/repositories/` for all database access.

MCP Servers and Extensions

# Configure an MCP server in ~/.gemini/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}
> @github List my open pull requests
> @slack Send a summary of today's commits to #dev

Troubleshooting

Best Practices

  1. Commit a GEMINI.md so the agent knows your conventions on every machine.
  2. Use headless mode in CI with --output-format json and parse the result.
  3. Pin the channel — use @latest for stability, @nightly only to test new features.
  4. Keep API keys in a secret store, never in a committed .env.
  5. Use trusted folders so the agent does not operate outside your project.
  6. Add MCP servers for the systems you use — pull requests, chat and issue trackers all work as tools.
  7. Migrate to Antigravity CLI if you are on the free tier or want the multi-agent workflow.

Next Steps

Claude Code

Install Anthropic's Claude Code with the native installer or the signed apt, dnf and apk repositories, authenticate, and verify the release signature.

Aider

Install Aider with the one-line installer, uv or pipx, connect it to a model provider and let it commit your changes to git as it works.