gemini-cli

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: gemini-cli
description: "Use this skill whenever the user wants to install, configure, or use the Gemini CLI (gemini-cli) tool. Trigger this skill for tasks such as: installing gemini-cli via npm/npx/brew, setting up authentication (API key, Google OAuth, Vertex AI), running non-interactive/headless prompts with -p flag, configuring settings.json, creating GEMINI.md context files, writing custom slash commands (.toml files), connecting MCP servers, creating extensions, automating tasks with shell scripts, using --output-format json/stream-json, managing chat sessions, using /memory commands, --auto-approve mode, Application Default Credentials (ADC), or any scripting/automation involving gemini-cli. Also trigger when user asks about integrating Gemini models into CLI workflows, CI/CD pipelines, or programmatic use of the Gemini API through the CLI tool."
---

# Gemini CLI Skill

Gemini CLI is an open-source AI agent that brings Gemini models directly into the terminal.
It supports interactive REPL sessions, headless/non-interactive scripting, MCP servers, custom
slash commands, and extension-based workflows.

**Reference files** (read when needed):
- `references/commands.md` — slash commands, built-in commands reference
- `references/configuration.md` — settings.json, GEMINI.md, environment variables
- `references/mcp-and-extensions.md` — MCP server setup, extensions authoring
- `references/headless-and-scripting.md` — non-interactive mode, automation, CI/CD patterns

---

## Installation

```bash
# Instant use, no install
npx @google/gemini-cli

# Global install (recommended)
npm install -g @google/gemini-cli

# macOS/Linux via Homebrew
brew install gemini-cli

# Specific channels
npm install -g @google/gemini-cli@latest    # stable (weekly Tuesdays)
npm install -g @google/gemini-cli@preview   # preview (weekly, less vetted)
npm install -g @google/gemini-cli@nightly   # nightly (daily builds)
```

---

## Authentication

Choose one method:

### Option 1: Google OAuth (recommended for individuals)
```bash
gemini   # → choose "Login with Google" → browser flow
```
- Free: 60 req/min, 1,000 req/day
- No API key needed

### Option 2: Gemini API Key
```bash
export GEMINI_API_KEY="your_key_here"
# Get key: https://aistudio.google.com/apikey
gemini
```
- Free: 1,000 req/day (Gemini Flash/Pro mix)
- Can also store in `~/.gemini/.env` or `./.gemini/.env`

### Option 3: Application Default Credentials (ADC)
```bash
gcloud auth application-default login
gemini
```
- Uses Google Cloud ADC — no API key needed
- Best for developers already using Google Cloud

### Option 4: Vertex AI (enterprise)
```bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
gcloud auth application-default login
gemini
```

---

## Basic Usage

```bash
# Start interactive session in current directory
gemini

# Include extra directories as context
gemini --include-directories ../lib,../docs

# Use a specific model
gemini -m gemini-2.5-flash
gemini -m gemini-2.5-pro

# Non-interactive: single prompt, then exit
gemini -p "Explain the architecture of this codebase"

# Reference files in prompt with @ syntax
gemini -p "Review @./src/auth.py for security issues"

# Pipe stdin
cat error.log | gemini -p "What went wrong here?"
git diff --cached | gemini -p "Write a concise commit message"
```

---

## Headless / Non-Interactive Mode

Headless mode is triggered by `-p` flag or non-TTY environment.

```bash
# Plain text output (default)
gemini -p "Explain Docker" > output.txt

# Structured JSON output (recommended for scripting)
gemini -p "Explain Docker" --output-format json

# Streaming JSONL (for long-running tasks)
gemini -p "Run tests and analyze results" --output-format stream-json

# Extract response field with jq
gemini -p "List top 5 Python testing frameworks" --output-format json | jq -r '.response'

# Auto-accept all tool actions (auto-approve mode) — use with care in automation
gemini -p "Generate unit tests for @./s