gemini-cli skill

---
name: gemini-cli
description: |
  Google Gemini CLI is a terminal-based AI coding agent for agentic development.
  Use when running gemini commands, configuring settings.json, creating GEMINI.md context files,
  setting up MCP servers, writing hooks, custom commands, or automating with headless mode.
  Key features: file editing, shell execution, web search, checkpointing, extensions, skills.
compatibility: Requires Node.js 18+. Install via npm install -g @google/gemini-cli.
allowed-tools: Read, Bash, Write
metadata:
  source: https://geminicli.com/docs/
  version: "0.22.x"
  updated: "2026-01-19"
---

# Gemini CLI Skill

## Overview

Gemini CLI is Google's open-source terminal-based AI coding agent that enables agentic development workflows. It allows Gemini models to reason, use tools (shell, file editing, web search), and execute multi-step plans directly in your terminal.

## Installation

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

# Run without installing
npx @google/gemini-cli

# Preview version (experimental features like Agent Skills)
npm install -g @google/gemini-cli@preview

# Run in Docker sandbox
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
```

## Authentication

```bash
# Option 1: Google Account Login (recommended for individuals)
gemini
# Select "Login with Google" and follow browser prompts

# Option 2: API Key (for automation/CI)
export GEMINI_API_KEY="your-api-key-from-aistudio.google.com"
gemini

# Option 3: Vertex AI (enterprise)
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
gcloud auth application-default login
gemini
# Select "Vertex AI"
```

## Quick Start

```bash
# Start interactive session
gemini

# One-shot prompt (headless mode)
gemini -p "Explain this codebase"

# With file context
cat README.md | gemini -p "Summarize this documentation"

# JSON output for scripting
gemini -p "List all TODO comments" --output-format json
```

## Configuration

### File Locations
- **User settings:** `~/.gemini/settings.json`
- **Project settings:** `.gemini/settings.json`
- **System settings:** `/etc/gemini-cli/settings.json`

### Essential settings.json

```json
{
  "general": {
    "vimMode": false,
    "checkpointing": { "enabled": true }
  },
  "ui": {
    "theme": "GitHub",
    "showCitations": true,
    "showModelInfoInChat": true
  },
  "model": {
    "name": "gemini-2.5-pro"
  },
  "tools": {
    "sandbox": "docker",
    "autoAccept": false,
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"]
  },
  "context": {
    "fileName": ["GEMINI.md", "CONTEXT.md"]
  }
}
```

## Core Commands

### Slash Commands (/)

| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/tools` | List available tools |
| `/model` | Select Gemini model |
| `/settings` | Open settings editor |
| `/memory show` | Display loaded context |
| `/memory refresh` | Reload GEMINI.md files |
| `/chat save <tag>` | Save conversation checkpoint |
| `/chat resume <tag>` | Resume saved conversation |
| `/restore` | Undo file changes (requires checkpointing) |
| `/compress` | Summarize chat to save tokens |
| `/mcp` | List MCP servers and tools |
| `/stats` | Show token usage statistics |
| `/init` | Generate GEMINI.md for current project |

### At Commands (@)

```bash
# Include file content in prompt
@path/to/file.txt Explain this code

# Include directory
@src/ Summarize the code structure

# Escape spaces
@My\ Documents/file.txt
```

### Shell Mode (!)

```bash
# Execute single command
!git status

# Toggle shell mode (type ! alone)
!
# Now in shell mode - all input goes to shell
# Type ! again to exit
```

## GEMINI.md Context Files

Create `.gemini/GEMINI.md` in your project root:

```markdown
# Project Context

## Overview
This is a TypeScript React application using Next.js 14.

## Coding Standards
- Use functional components with hooks
- Prefer TypeScript strict mode
- Follow Airbnb ESLint rules

## Architecture
- `src/components/` - React components
- `src/lib/` - Utility functions
- `src/app/` - Next.js app router pages

## Important Notes
- Always run `npm test` before committing
- Use conventional commits format
```

### Modular Context (Import Files)

```markdown
# Main GEMINI.md
@./docs/api-guidelines.md
@../shared/coding-standards.md
```

## Custom Commands

Create reusable prompts in `.gemini/commands/`:

**File: `~/.gemini/commands/review.toml`**
```toml
description = "Review code for issues"
prompt = """
Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Code style violations

Provide specific line-by-line feedback.
"""
```

**File: `.gemini/commands/git/commit.toml`**
```toml
description = "Generate commit message from staged changes"
prompt = """
Generate a Conventional Commit message based on:
```diff
!{git diff --staged}
```
"""
```

Usage: `/review` or `/git:commit`

## Headless Mode (Automation)

```bash
# Basic usage
gemini -p "What is the capital of France?"

# JSON output
gemini -p "List all functions" --output-format json | jq '.response'

# Streaming JSON (real-time events)
gemini -p "Refactor this code" --output-format stream-json

# Auto-approve all actions (YOLO mode)
gemini -p "Fix all lint errors" --yolo

# Auto-approve edits only
gemini -p "Update README" --approval-mode auto_edit

# Include directories
gemini -p "Analyze the code" --include-directories src,docs
```

### CI/CD Integration

```yaml
# .github/workflows/review.yml
steps:
  - uses: actions/checkout@v4
  - uses: google-github-actions/run-gemini-cli@v0
    with:
      gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
      prompt: "Review PR #${{ github.event.pull_request.number }}"
```

## Built-in Tools

| Tool | Purpose |
|------|---------|
| `read_file` | Read file contents |
| `write_file` | Create/overwrite files |
| `replace` | Edit file with find/replace |
| `list_directory` | List directory contents |
| `glob` | Find files by pattern |
| `search_file_content` | Grep/search in files |
| `run_shell_command` | Execute shell commands |
| `google_web_search` | Search the web |
| `web_fetch` | Fetch URL content |
| `save_memory` | Save to GEMINI.md |
| `write_todos` | Manage task lists |

## Common Gotchas

1. **Org account requires project:** Set `GOOGLE_CLOUD_PROJECT` for Workspace/company accounts
2. **DEBUG env var excluded:** Use `.gemini/.env` not project `.env` for debug settings
3. **SSL certificate errors:** Set `NODE_USE_SYSTEM_CA=1` on corporate networks
4. **Sandbox MCP issues:** Tools must be available inside the sandbox container
5. **Session not interactive in CI:** Unset `CI_*` env vars if needed

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `GEMINI_API_KEY` | API key from AI Studio |
| `GEMINI_MODEL` | Default model name |
| `GOOGLE_CLOUD_PROJECT` | GCP project ID |
| `GOOGLE_CLOUD_LOCATION` | GCP region (e.g., us-central1) |
| `GEMINI_SANDBOX` | Enable sandbox (true/docker/podman) |
| `GEMINI_SYSTEM_MD` | Path to custom system prompt |

## Best Practices

1. **Use GEMINI.md:** Always create project-specific context files
2. **Enable checkpointing:** Set `general.checkpointing.enabled: true` for undo capability
3. **Use sandbox for safety:** Enable Docker sandbox when running untrusted commands
4. **Be specific in prompts:** Include file paths, expected behavior, and constraints
5. **Ask for a plan first:** Request the agent to outline steps before making changes
6. **Use shell mode for quick commands:** Toggle with `!` for faster terminal access
7. **Leverage custom commands:** Create `.toml` files for repetitive workflows

## Additional Resources

- [API Reference](references/API.md) - Complete tools and commands
- [Examples](references/EXAMPLES.md) - Practical code snippets
- [Troubleshooting](references/TROUBLESHOOTING.md) - Error solutions
- [Advanced Features](references/ADVANCED.md) - MCP, hooks, extensions, sandboxing