# Gemini Web MCP CLI - Command Reference

Complete command signatures for `gemcli` and the `gemini-web-mcp` MCP server.

---

## Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--profile` | `-p` | Use a specific profile for this command |
| `--verbose` | `-v` | Enable debug logging |
| `--version` | | Show version |
| `--ai` | | Output AI-friendly documentation |
| `--install-completion` | | Install shell completion |
| `--show-completion` | | Display completion script |

---

## Authentication

### `gemcli login`

Authenticate with Google Gemini via Chrome CDP or manual cookie entry.

```bash
gemcli login                          # Automated Chrome login via CDP
gemcli login --check                  # Validate current session
gemcli login --manual                 # Paste cookies manually
gemcli login --profile <name>         # Authenticate a specific profile
```

| Option | Description |
|--------|-------------|
| `--check` | Validate current auth without re-authenticating |
| `--manual` | Manual cookie entry mode |
| `--profile, -p` | Profile to authenticate |

---

## Chat

### `gemcli chat [PROMPT]`

Send messages to Gemini. Without a prompt, opens interactive REPL.

```bash
gemcli chat "What is quantum computing?"
gemcli chat "Explain this" -m gemini-3.0-pro
gemcli chat "Summarize" -o summary.md
gemcli chat "Analyze this" -f document.pdf
gemcli chat "Compare" -f file1.md -f file2.md
gemcli chat --new                     # Force new conversation
gemcli chat                           # Interactive REPL
```

| Option | Short | Description |
|--------|-------|-------------|
| `--model` | `-m` | Model to use (e.g., gemini-3.0-pro) |
| `--output` | `-o` | Save response to file |
| `--file` | `-f` | Attach a file (can be used multiple times) |
| `--new` | | Start new conversation (discard context) |
| `--gem` | | Use a specific Gem by ID |

**Interactive REPL Slash Commands:**

| Command | Description |
|---------|-------------|
| `/model <name>` | Switch model |
| `/verify` | Show server model hash |
| `/new` | Start new conversation |
| `/save <file>` | Export conversation |
| `/history` | View conversation turns |
| `/help` | Show help |
| `/quit` | Exit REPL |

---

## Image Generation

### `gemcli image PROMPT`

Generate images using Gemini (Nano Banana / Imagen). Requires Chrome for BotGuard token and tool activation (`gemcli chrome start`).

```bash
gemcli image "A red panda in bamboo"
gemcli image "Futuristic city" -o city.png
gemcli image "Logo design" -m gemini-3.0-pro
```

| Option | Short | Description |
|--------|-------|-------------|
| `--model` | `-m` | `flash` (Nano Banana 2, default) or `pro` (Nano Banana Pro) |
| `--output` | `-o` | Save generated image to file |

---

## Video Generation

### `gemcli video PROMPT`

Generate videos using Gemini (Veo 3.1). Videos take 1-2 minutes. Requires Chrome for BotGuard token and tool activation (`gemcli chrome start`).

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

| Option | Short | Description |
|--------|-------|-------------|
| `--model` | `-m` | Model to use |
| `--output` | `-o` | Save generated video to file |

---

## File Upload

### `gemcli file upload <FILE_PATH>`

Upload a file to Gemini and get its identifier.

```bash
gemcli file upload document.pdf
gemcli file upload screenshot.png
```

**Note:** For most use cases, use `gemcli chat -f <file>` instead — it handles upload + chat in one step.

---

### `gemcli chat -f <FILE_PATH>`

Attach one or more files to a chat message. Files are uploaded automatically.

```bash
gemcli chat "Summarize this" -f report.pdf
gemcli chat "What's in this image?" -f photo.jpg
gemcli chat "Compare these" -f a.md -f b.md
```

Requires Chrome for BotGuard token. Run `gemcli chrome start` first.

---

## Music Generation

### `gemcli music [PROMPT]`

Generate 30-second music tracks using Gemini (Lyria 3). Includes vocals, lyrics, instrumentals, and auto-generated cover art. Without a prompt and with `--list-styles`, shows available style presets.

```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
```

| Option | Short | Description |
|--------|-------|-------------|
| `--model` | `-m` | Model to use |
| `--output` | `-o` | Save generated track to file |
| `--style` | `-s` | Style preset (e.g., 8-bit, k-pop, cinematic) |
| `--format` | `-f` | Output format: `audio` (MP3, default) or `video` (MP4 with cover art) |
| `--list-styles` | | Show all 16 available style presets and exit |

**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.

---

## Deep Research

### `gemcli research QUERY`

Run deep research queries with multi-source analysis.

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

| Option | Short | Description |
|--------|-------|-------------|
| `--model` | `-m` | Model to use |
| `--output` | `-o` | Save research report to file |

---

## Usage Limits

### `gemcli limits`

Show current usage limits and remaining quota for all features. Requires Chrome for browser cookie authentication (Token Factory).

```bash
gemcli limits
```

Displays per-feature data including: video (Veo 3.1), music (Lyria 3), images, Pro prompts, Thinking prompts, Deep Research, Agent requests, and more. Each feature shows current usage, daily limit, remaining count, and rolling reset time.

---

## Gems Management

### `gemcli gems list`

List all custom Gems.

```bash
gemcli gems list
gemcli gems list --predefined        # Include predefined Gems
```

| Option | Description |
|--------|-------------|
| `--predefined` | Include system/predefined gems |

### `gemcli gems create`

Create a new custom Gem.

```bash
gemcli gems create --name "Code Reviewer" --prompt "You are a senior code reviewer..."
gemcli gems create --name "Writer" --description "Creative writing" --prompt "..."
```

| Option | Description |
|--------|-------------|
| `--name` | Display name (required) |
| `--description` | Short description |
| `--prompt` | System prompt text (required) |

### `gemcli gems delete GEM_ID`

Delete a Gem by ID.

```bash
gemcli gems delete abc123
```

---

## Profile Management

### `gemcli profile list`

List all profiles (gemcli-native + NotebookLM shared).

### `gemcli profile switch NAME`

Switch the active profile.

### `gemcli profile create NAME`

Create a new profile.

### `gemcli profile delete NAME`

Delete a profile (requires confirmation).

### `gemcli profile sources`

Show profile sources (gemcli-native vs NLM shared).

---

## Persistent Chrome

### `gemcli chrome start`

Start a persistent Chrome daemon for Token Factory. Required for image generation, video generation, music generation, and Pro/Thinking models. Must be run from an interactive terminal.

```bash
gemcli chrome start              # Start headless (default)
gemcli chrome start --visible    # Start with visible window
gemcli chrome start -p 9225      # Use specific CDP port
```

| Option | Short | Description |
|--------|-------|-------------|
| `--visible` | | Show Chrome window instead of headless |
| `--port` | `-p` | Specific CDP debugging port (default: auto from 9222-9231) |

Chrome runs in the background and survives terminal close. Token Factory automatically detects it on ports 9222-9231.

### `gemcli chrome stop`

Stop the persistent Chrome daemon.

```bash
gemcli chrome stop
```

### `gemcli chrome status`

Show Chrome daemon health, port, uptime, and Gemini auth status.

```bash
gemcli chrome status
```

---

## Configuration

### `gemcli config show`

Display all current settings.

### `gemcli config get KEY`

Get a specific configuration value.

### `gemcli config set KEY VALUE`

Set a configuration value.

**Available Keys:**

| Key | Default | Description |
|-----|---------|-------------|
| `active_profile` | `default` | Active profile name |
| `default_model` | (none) | Default model for commands |

---

## MCP Setup

### `gemcli setup list`

Show all supported AI tools and their MCP configuration status.

### `gemcli setup add CLIENT`

Add Gemini Web MCP server to an AI tool.

```bash
gemcli setup add cursor
gemcli setup add claude-desktop
gemcli setup add claude-code
gemcli setup add gemini-cli
gemcli setup add windsurf
gemcli setup add cline
gemcli setup add antigravity
```

### `gemcli setup remove CLIENT`

Remove Gemini Web MCP server from an AI tool.

---

## Skill Management

### `gemcli skill list`

Show available tools and skill installation status.

### `gemcli skill install TOOL`

Install Gemini skill documentation for an AI tool.

```bash
gemcli skill install claude-code
gemcli skill install cursor
gemcli skill install codex
gemcli skill install gemini-cli
```

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--level` | `-l` | `user` | Install at user or project level |

### `gemcli skill uninstall TOOL`

Remove installed Gemini skill.

### `gemcli skill update [TOOL]`

Update outdated skills. If TOOL omitted, updates all.

### `gemcli skill show`

Display the full skill documentation content.

---

## Hack (Launch AI Tools via Gemini)

### `gemcli hack claude [OPTIONS]`

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

```bash
gemcli hack claude                         # Default: gemini-auto (Flash)
gemcli hack claude --model gemini-pro      # Use Gemini Pro
gemcli hack claude -p "fix this bug"       # Pass args to Claude Code
```

All arguments after `claude` are passed through to Claude Code.

**Available models:** `gemini-auto` (Flash, default), `gemini-flash`, `gemini-pro`, `gemini-thinking`.

---

## Diagnostics

### `gemcli doctor`

Diagnose installation, authentication, and configuration.

```bash
gemcli doctor              # Standard diagnostics
gemcli doctor --verbose    # Detailed diagnostics with paths and timestamps
```

---

## MCP Server Tools

The `gemini-web-mcp` MCP server exposes these tools:

### `chat`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"send"` |
| `prompt` | string | for send | Message to send |
| `model` | string | no | Model: "pro", "flash", "thinking" |
| `conversation_id` | string | no | Continue existing conversation |
| `extensions` | list[str] | no | Extensions: ["youtube", "maps"] |
| `files` | list[str] | no | Local file paths to upload and attach |

### `image`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"generate"` or `"download"` |
| `prompt` | string | for generate | Image description |
| `model` | string | no | `"flash"` (default, Nano Banana 2) or `"pro"` (Nano Banana Pro) |
| `image_url` | string | for download | URL from generate response |
| `output_path` | string | for download | Local file path |

### `video`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"generate"`, `"status"`, or `"download"` |
| `prompt` | string | for generate | Video description |
| `model` | string | no | Model to use |
| `output_path` | string | for download | Local file path |

### `music`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"generate"`, `"list_styles"`, or `"download"` |
| `prompt` | string | for generate | Music description / concept |
| `style` | string | no | Style preset name (e.g., "8-bit", "k-pop", "cinematic") |
| `output_path` | string | no | Auto-download generated track to this path |
| `download_url` | string | for download | URL from a previous generation |

**Actions:**
- `generate` — Generate a 30-second track. Returns track metadata, lyrics, and download URLs (MP3 + MP4).
- `list_styles` — Returns all 16 available style preset names.
- `download` — Download a track from a previous generation URL.

### `research`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"start"` or `"status"` |
| `query` | string | for start | Research question |
| `model` | string | no | Model to use |

### `file`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"upload"` |
| `file_path` | string | for upload | Local path to the file |

### `gems`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | yes | `"list"`, `"create"`, `"update"`, `"delete"` |
| `gem_id` | string | for update/delete | Gem identifier |
| `name` | string | for create | Display name |
| `description` | string | no | Short description |
| `system_prompt` | string | for create | System prompt text |

### Stub Tools (Coming Soon)

- **`canvas`**: Collaborative document editing (actions: create, update, export)
- **`code`**: Python code execution in Gemini's sandbox (actions: execute, download)
- **`file`**: File upload for conversation context (actions: upload)

---

## Verb-First Aliases

These aliases provide an alternative command style:

```bash
gemcli list gems                 # = gemcli gems list
gemcli list profiles             # = gemcli profile list
gemcli list skills               # = gemcli skill list
gemcli create gem --name ...     # = gemcli gems create --name ...
gemcli delete gem <id>           # = gemcli gems delete <id>
gemcli install skill <tool>      # = gemcli skill install <tool>
gemcli update skill [tool]       # = gemcli skill update [tool]
```
