---
name: gemini-web-skill
description: "Expert guide for the Gemini Web MCP CLI (`gemcli`) and MCP server - interfaces for Google Gemini (gemini.google.com). Use this skill when users want to interact with Gemini programmatically, including: chatting with models, generating images, generating videos, generating music, deep research, managing Gems (custom personas), or automating Gemini workflows. Triggers on mentions of \"gemcli\", \"gemini web mcp\", \"gemini chat\", \"image generation\", \"video generation\", \"music generation\", \"deep research\", \"gems\", or any Gemini web-related automation task."
---

# Gemini Web MCP CLI & MCP Expert

This skill provides comprehensive guidance for using Google Gemini via both the `gemcli` CLI and MCP tools.

## Tool Detection (CRITICAL - Read First!)

**ALWAYS check which tools are available before proceeding:**

1. **Check for MCP tools**: Look for tools starting with `mcp__gemini-web-mcp__*`
2. **If BOTH MCP tools AND CLI are available**: **ASK the user** which they prefer
3. **If only MCP tools are available**: Use them directly (refer to tool docstrings for parameters)
4. **If only CLI is available**: Use `gemcli` CLI commands via Bash

**Decision Logic:**
```
has_mcp_tools = check_available_tools()  # Look for mcp__gemini-web-mcp__*
has_cli = check_bash_available()          # Can run gemcli commands

if has_mcp_tools and has_cli:
    # ASK USER: "I can use either MCP tools or the gemcli CLI. Which do you prefer?"
    user_preference = ask_user()
elif has_mcp_tools:
    # Use MCP tools directly
    mcp__gemini-web-mcp__chat(action="send", prompt="Hello")
else:
    # Use CLI via Bash
    bash("gemcli chat 'Hello'")
```

This skill documents BOTH approaches. Choose based on tool availability and **user preference**.

## Quick Reference

**Run `gemcli --ai` to get comprehensive AI-optimized documentation.**

```bash
gemcli --help              # List all commands
gemcli <command> --help    # Help for specific command
gemcli --ai                # Full AI-optimized documentation (RECOMMENDED)
gemcli --version           # Check installed version
gemcli doctor              # Diagnose installation and auth
```

## Critical Rules (Read First!)

1. **Always authenticate first**: Run `gemcli login` before any operations
2. **Session expiry**: Cookies can expire — auto-recovery handles this silently (see below)
3. **Model selection**: Default is Flash (fast, no special setup). Pro and Thinking require Token Factory (Chrome + BotGuard token)
4. **Music generation requires Chrome**: Music (Lyria 3) needs a BotGuard token even on Flash. Start persistent Chrome first: `gemcli chrome start`
5. **Video generation requires Chrome**: Video (Veo 3.1) needs BotGuard + tool activation. Start persistent Chrome first: `gemcli chrome start`
6. **Image generation requires Chrome**: Image generation needs BotGuard + tool activation. Defaults to Nano Banana 2 (Gemini 3.1 Flash Image); use `-m pro` for Nano Banana Pro (Pro/Ultra subscribers). Start persistent Chrome first: `gemcli chrome start`
7. **Interactive chat**: `gemcli chat` without a prompt opens an interactive REPL with slash commands
8. **NotebookLM cross-product**: If you have NotebookLM MCP installed, gemcli can reuse its Chrome profiles
9. **Background processes (LaunchAgent/cron)**: Cannot launch Chrome. Start persistent Chrome from an interactive terminal first: `gemcli chrome start`
10. **Use `--help` when unsure**: Run `gemcli <command> --help` for available options

## Authentication Error Recovery (AI AGENTS — MANDATORY)

**When you encounter ANY authentication error** — including `AuthError`, expired cookies, "Are you signed in?", "can't create it right now", `TokenFactoryError`, or any response suggesting the session is invalid — you **MUST** follow this protocol:

1. **Run `gemcli login`** (no flags) — this silently refreshes cookies via CDP in ~5 seconds. No user interaction needed.
2. **Retry your original command exactly once.**
3. **Only if step 2 fails again**, notify the user that authentication needs manual intervention and suggest running `gemcli login --force`.

**DO NOT** stop what you are doing.  
**DO NOT** ask the user before running step 1.  
**DO NOT** notify the user unless step 2 also fails.  
**Just run it, retry, and continue your task.**

```bash
# Example: image generation fails with auth error
gemcli image "A sunset"       # ❌ "Are you signed in?" or AuthError
gemcli login                   # 🔄 Silent refresh (~5 seconds)
gemcli image "A sunset"       # ✅ Retry — should work now
# Only notify user if this second attempt also fails
```

## Workflow Decision Tree

```
User wants to...
|
+--> Chat with Gemini
|    +--> Single message -> gemcli chat "prompt" [-m model]
|    +--> With file(s) -> gemcli chat "analyze" -f file.pdf [-f file2.png]
|    +--> Interactive REPL -> gemcli chat (no prompt)
|    +--> With extensions -> gemcli chat "@youtube summarize ..."
|
+--> Upload files
|    +--> With chat -> gemcli chat "describe this" -f image.png
|    +--> Standalone -> gemcli file upload document.pdf
|
+--> Generate images
|    +--> gemcli image "prompt" [-o output.png]
|
+--> Generate videos (Veo 3.1)
|    +--> gemcli video "prompt" [-o output.mp4]
|
+--> Generate music (Lyria 3)
|    +--> gemcli music "prompt" [-o track.mp3]
|    +--> With style preset -> gemcli music "prompt" -s 8-bit
|    +--> List presets -> gemcli music --list-styles
|
+--> Deep Research
|    +--> gemcli research "query" [-m model]
|
+--> Manage Gems (custom personas)
|    +--> List gems -> gemcli gems list
|    +--> Create gem -> gemcli gems create --name "Name" --prompt "..."
|    +--> With NotebookLM -> gemcli gems create ... --notebook <uuid>
|    +--> Delete gem -> gemcli gems delete <gem_id>
|
+--> First-time setup
|    +--> gemcli login -> gemcli doctor
|
+--> Persistent Chrome (for music, Pro model, or background processes)
|    +--> gemcli chrome start           # Start headless Chrome daemon
|    +--> gemcli chrome status          # Check if running + authenticated
|    +--> gemcli chrome stop            # Stop Chrome daemon
|
+--> Check usage limits / remaining quota
|    +--> gemcli limits              # Per-feature usage, limits, and reset times
|
+--> Use Gemini inside Claude Code
|    +--> gemcli hack claude                  # Launch with default model
|    +--> gemcli hack claude --model gemini-pro
|
+--> Configure AI tools
     +--> gemcli setup add <tool>    (MCP server)
     +--> gemcli skill install <tool> (skill docs)
```

## Command Categories

### 1. Authentication

#### CLI Authentication
```bash
gemcli login                    # Automated Chrome login via CDP
gemcli login --check            # Validate current session
gemcli login --manual           # Paste cookies manually
gemcli login --profile work     # Use named profile
```

#### MCP Authentication
If using MCP tools and encountering auth errors, run `gemcli login` from the CLI to refresh cookies.

### 2. Chat

#### MCP Tool
```python
mcp__gemini-web-mcp__chat(action="send", prompt="Hello", model="pro")
mcp__gemini-web-mcp__chat(action="send", prompt="Follow up", conversation_id="abc123")
mcp__gemini-web-mcp__chat(action="send", prompt="@youtube summarize this", extensions=["youtube"])
mcp__gemini-web-mcp__chat(action="send", prompt="Analyze this", files=["/path/to/doc.pdf"])
```

#### CLI Commands
```bash
gemcli chat "What is quantum computing?"          # Single message
gemcli chat "Explain this" -m gemini-3.0-pro      # Use Pro model
gemcli chat "Summarize" -o summary.md             # Save to file
gemcli chat "Analyze this" -f document.pdf        # Chat with file attachment
gemcli chat "Compare" -f a.md -f b.md             # Multiple files
gemcli chat                                        # Interactive REPL
```

**Interactive REPL Slash Commands:**
- `/model <name>` - Switch model
- `/verify` - Show server model hash
- `/new` - Start new conversation
- `/save <file>` - Export conversation
- `/history` - View turns
- `/help` - Show help
- `/quit` - Exit

### 3. Image Generation

#### MCP Tool
```python
mcp__gemini-web-mcp__image(action="generate", prompt="A sunset", output_path="sunset.png")
mcp__gemini-web-mcp__image(action="download", image_url="https://...", output_path="img.png")
```

#### CLI Commands
```bash
gemcli image "A red panda in bamboo"               # Generate and display
gemcli image "Futuristic city" -o city.png          # Generate and save
gemcli image "Logo design" -m gemini-3.0-pro        # Specify model
```

### 4. Video Generation (Veo 3.1)

#### MCP Tool
```python
mcp__gemini-web-mcp__video(action="generate", prompt="Ocean waves at sunset")
mcp__gemini-web-mcp__video(action="status")         # Check progress
```

#### CLI Commands
```bash
gemcli video "Ocean waves at sunset"
gemcli video "Dancing robot" -o robot.mp4
```

### 5. Music Generation (Lyria 3)

Generates 30-second music tracks with vocals, lyrics, instrumentals, and auto-generated cover art. Supports 16 style presets that mirror Gemini's "Pick a track to remix" page.

#### MCP Tool
```python
# Generate a track
mcp__gemini-web-mcp__music(action="generate", prompt="A comical R&B slow jam about a sock")

# Generate with a style preset
mcp__gemini-web-mcp__music(action="generate", prompt="Cats playing games", style="8-bit")

# Generate and auto-download
mcp__gemini-web-mcp__music(action="generate", prompt="Summer vibes", style="k-pop", output_path="track.mp3")

# List available style presets
mcp__gemini-web-mcp__music(action="list_styles")

# Download a track from a previous generation
mcp__gemini-web-mcp__music(action="download", download_url="https://...", output_path="track.mp3")
```

#### CLI Commands
```bash
gemcli music "A comical R&B slow jam about a sock"
gemcli music "Cats playing video games" -s 8-bit -o track.mp3
gemcli music "Summer vibes" -s k-pop -o video.mp4 -f video
gemcli music --list-styles                  # Show all 16 style presets
```

**Available Style Presets:** 90s-rap, latin-pop, folk-ballad, 8-bit, workout, reggaeton, rnb-romance, kawaii-metal, cinematic, emo, afropop, forest-bath, k-pop, birthday-roast, folk-a-cappella, bad-music.

**Aliases:** rap, latin, folk, chiptune, edm, rnb, r&b, kawaii, metal, orchestral, ambient, kpop, birthday, roast, country, acappella, bad.

### 6. File Upload

Upload files (images, PDFs, documents, audio) to provide context for chat conversations.

#### MCP Tool
```python
# Upload a file and get its identifier
mcp__gemini-web-mcp__file(action="upload", file_path="/path/to/document.pdf")

# Chat with file attachments (handles upload automatically)
mcp__gemini-web-mcp__chat(action="send", prompt="Summarize this", files=["/path/to/doc.pdf"])
```

#### CLI Commands
```bash
gemcli chat "What is this?" -f image.png              # Attach file to chat
gemcli chat "Compare these files" -f a.md -f b.md     # Multiple attachments
gemcli file upload document.pdf                        # Standalone upload
```

**Notes:**
- File attachments require Chrome (BotGuard token needed). Run `gemcli chrome start` first.
- Supported types: images (PNG, JPEG, GIF, WebP), PDFs, text files, audio files.
- Files expire after ~1 day (`ttl_1d` in the identifier).

### 7. Deep Research

#### MCP Tool
```python
mcp__gemini-web-mcp__research(action="start", query="AI advances in 2026")
mcp__gemini-web-mcp__research(action="status")       # Check progress
```

#### CLI Commands
```bash
gemcli research "Latest AI advances in 2026"
gemcli research "Quantum computing breakthroughs" -m gemini-3.0-pro
```

### 8. Gems (Custom Personas)

#### MCP Tool
```python
mcp__gemini-web-mcp__gems(action="list")
mcp__gemini-web-mcp__gems(action="list_notebooks")  # List NotebookLM notebooks for attachment
mcp__gemini-web-mcp__gems(action="create", name="Reviewer", system_prompt="You are...")
mcp__gemini-web-mcp__gems(action="create", name="Researcher", system_prompt="...",
    notebook_ids=["uuid1", "uuid2"])  # Attach NotebookLM notebooks as knowledge
mcp__gemini-web-mcp__gems(action="update", gem_id="abc", name="New Name",
    notebook_ids=["uuid1"])  # Update with notebook knowledge
mcp__gemini-web-mcp__gems(action="delete", gem_id="abc")
```

#### CLI Commands
```bash
gemcli gems list
gemcli gems create --name "Code Reviewer" --prompt "You are a senior code reviewer..."
gemcli gems create --name "Expert" --prompt "..." --notebook <uuid>  # With NotebookLM
gemcli gems create --name "Multi" --prompt "..." --notebook <id1> --notebook <id2>
gemcli gems delete <gem_id>
```

**NotebookLM Integration:** Use `list_notebooks` to find notebook IDs, then pass them via `notebook_ids` (MCP) or `--notebook` (CLI) when creating or updating gems. Notebooks are attached as knowledge sources the gem can reference. Up to 10 knowledge sources per gem (files + notebooks combined).

### 9. Profile Management

```bash
gemcli profile list              # List all profiles (gemcli + NLM shared)
gemcli profile switch <name>     # Switch active profile
gemcli profile create <name>     # Create new profile
gemcli profile delete <name>     # Delete profile
gemcli profile sources           # Show profile sources
```

### 10. Persistent Chrome (for background processes)

Some features require Chrome for BotGuard token generation:
- **File uploads / attachments** — BotGuard required for chat with files
- **Image generation** (Imagen) — BotGuard + tool activation required
- **Video generation** (Veo 3.1) — BotGuard + tool activation required
- **Music generation** (Lyria 3) — always needs BotGuard, even on Flash model
- **Pro/Thinking models** — need BotGuard for model switching

If running from a **background process** (macOS LaunchAgent, cron, systemd, SSH without display), Chrome cannot be launched on demand. Start it once from an interactive terminal:

```bash
gemcli chrome start              # Start headless Chrome daemon (survives terminal close)
gemcli chrome start --visible    # Start with visible window (for debugging)
gemcli chrome start -p 9225      # Use specific CDP port
gemcli chrome stop               # Stop the daemon
gemcli chrome status             # Check health, port, auth status, uptime
```

**How it works:** Token Factory automatically detects the running Chrome on ports 9222-9231. No configuration needed — just start it and music/Pro features work from any context.

**After reboot:** Run `gemcli chrome start` again from an interactive terminal.

### 11. Configuration

```bash
gemcli config show               # Show all settings
gemcli config get <key>          # Get specific value
gemcli config set <key> <value>  # Set a value
```

### 12. MCP Setup

```bash
gemcli setup list                # Show configured clients
gemcli setup add cursor          # Add to Cursor
gemcli setup add claude-desktop  # Add to Claude Desktop
gemcli setup add claude-code     # Add to Claude Code
gemcli setup add gemini-cli      # Add to Gemini CLI
gemcli setup remove <tool>       # Remove from tool
```

### 13. Skill Management

```bash
gemcli skill list                # Show installation status
gemcli skill install claude-code # Install for Claude Code
gemcli skill install cursor      # Install for Cursor
gemcli skill update              # Update all outdated skills
gemcli skill show                # Display skill content
```

### 14. Hack Claude (Launch Claude Code via Gemini)

Launch Claude Code connected to a local Anthropic-compatible API server backed by Gemini.

```bash
gemcli hack claude                         # Launch with Gemini Flash (default)
gemcli hack claude --model gemini-pro      # Use Gemini Pro
gemcli hack claude -p "fix this bug"       # Pass args through to Claude Code
```

**How it works:** Starts a local FastAPI server on a free port that implements the Anthropic Messages API, sets `ANTHROPIC_BASE_URL` to point to it, and launches `claude`. When Claude Code exits, the server is automatically shut down.

**Requirements:** Claude Code must be installed (`npm install -g @anthropic-ai/claude-code`).

### 15. Diagnostics

```bash
gemcli doctor                    # Check installation, auth, config
gemcli doctor --verbose          # Detailed diagnostics
```

### 16. Usage Limits

```bash
gemcli limits                    # Show per-feature usage quotas and remaining count
```

Requires Chrome for browser cookie authentication (Token Factory). Shows video, music, images, prompts, research quotas with remaining count and reset time.

#### MCP Tool
```python
mcp__gemini-web-mcp__limits()    # Returns JSON with per-feature limit data
```

**IMPORTANT**: Call `limits` before attempting video, music, or image generation to verify quota is available. This avoids wasting time on operations that will be rejected.

## Model Selection Guide

| Model | CLI Flag | Notes |
|-------|----------|-------|
| Flash (default) | `-m gemini-3.0-flash` | Fast, direct HTTP, no special setup |
| Pro | `-m gemini-3.0-pro` | Requires Token Factory (Chrome + BotGuard) |
| Thinking | `-m gemini-3.0-flash-thinking` | Requires Token Factory (Chrome + BotGuard) |

**Token Factory**: Pro and Thinking models require a BotGuard token generated by Chrome. Flash works with direct HTTP (no browser needed).

## Error Recovery

| Error | Cause | Solution |
|-------|-------|----------|
| AuthError / expired cookies | Session timeout | Run `gemcli login` (auto-recovers silently). See **Authentication Error Recovery** section above — AI agents MUST follow the 3-step protocol. |
| UsageLimitExceeded (1037) | Too many requests | Wait, then retry |
| ModelInvalid (1050/1052) | Bad model name | Check model names above |
| TemporarilyBlocked (1060) | IP rate limited | Wait or use VPN |
| TokenFactoryError | Chrome/BotGuard issue | Run `gemcli login` first. If still failing: check Chrome is installed, run `gemcli doctor`. For background processes: `gemcli chrome start` from interactive terminal |
| MusicGenerationError | Music generation failed | Check prompt, retry; content policy may reject some prompts |
| Chrome doesn't launch | Port conflict | Close Chrome, retry |

## Advanced Reference

For detailed information, see:
- **[references/command_reference.md](references/command_reference.md)**: Complete command signatures
- **[references/troubleshooting.md](references/troubleshooting.md)**: Detailed error handling
- **[references/workflows.md](references/workflows.md)**: End-to-end task sequences
