# Gemini Web MCP CLI - Workflows

End-to-end task sequences for common operations.

---

## AI Behavior Rules

**CRITICAL: Always follow these rules when using gemcli on behalf of a user:**

1. **Confirm before destructive operations**: Before deleting gems or profiles, show what will be deleted and ask for explicit user confirmation
2. **Check auth first**: Run `gemcli login --check` before starting a workflow to avoid mid-workflow auth failures
3. **Capture IDs from output**: Create commands return IDs needed for subsequent operations
4. **Report errors clearly**: If a command fails, show the error and suggest next steps

**Commands requiring user confirmation before execution:**
- `gemcli gems delete <id>`
- `gemcli profile delete <name>`

---

## Workflow 1: First-Time Setup

Goal: Get gemcli installed, authenticated, and verified.

```bash
# Step 1: Authenticate
gemcli login

# Step 2: Verify everything works
gemcli doctor

# Step 3: Test with a quick chat
gemcli chat "Hello, what can you do?"

# Step 4: (Optional) Set up AI tool integration
gemcli setup add claude-code
gemcli skill install claude-code
```

---

## Workflow 2: Chat with Model Selection

Goal: Chat using different models for different tasks.

```bash
# Quick answer with Flash (default, fastest)
gemcli chat "What is the capital of France?"

# Detailed analysis with Pro
gemcli chat "Analyze the pros and cons of microservices architecture" -m gemini-3.0-pro

# Reasoning-heavy task with Thinking
gemcli chat "Solve this logic puzzle: ..." -m gemini-3.0-flash-thinking

# Save response to file
gemcli chat "Write a summary of quantum computing" -o quantum_summary.md
```

**Interactive session with model switching:**
```bash
gemcli chat
# In REPL:
# /model gemini-3.0-pro     (switch to Pro)
# What are the latest trends in AI?
# /model gemini-3.0-flash   (switch back to Flash)
# Summarize that in one sentence
# /save conversation.md     (save the conversation)
# /quit
```

---

## Workflow 3: Image Generation Pipeline

Goal: Generate and save images.

```bash
# Generate with auto-save
gemcli image "A serene mountain landscape at sunset, photorealistic" -o landscape.png

# Generate without saving (displays URL)
gemcli image "An abstract painting of creativity"
# Then download specific image:
# Copy the image URL from the output and use the MCP download action
```

**Via MCP tools:**
```python
# Generate
result = mcp__gemini-web-mcp__image(
    action="generate",
    prompt="A futuristic cityscape at night",
    output_path="city.png"
)

# Download a specific URL later
mcp__gemini-web-mcp__image(
    action="download",
    image_url="https://...",
    output_path="city_v2.png"
)
```

---

## Workflow 4: Video Generation Pipeline

Goal: Generate a video with Veo 3.1. Requires Chrome for BotGuard token and tool activation.

```bash
# Prerequisite: ensure Chrome is running
gemcli chrome start

# Start generation (takes 1-2 minutes)
gemcli video "A drone shot flying over a tropical beach at golden hour"

# The command will poll for completion and save when ready
# Use -o to specify output path:
gemcli video "Dancing robot in a disco" -o robot_dance.mp4
```

**Via MCP tools:**
```python
# Start generation
mcp__gemini-web-mcp__video(action="generate", prompt="Ocean waves crashing")

# Check status
mcp__gemini-web-mcp__video(action="status")

# Download when complete
mcp__gemini-web-mcp__video(action="download", output_path="ocean.mp4")
```

---

## Workflow 5: Music Generation Pipeline

Goal: Generate music tracks with Lyria 3, with optional style presets.

```bash
# Generate a track (waits for completion, displays metadata + download URLs)
gemcli music "A comical R&B slow jam about a sock"

# Generate with a style preset
gemcli music "Cats playing video games" -s 8-bit

# Save as audio (MP3)
gemcli music "Epic orchestral battle theme" -s cinematic -o battle.mp3

# Save as video (MP4 with cover art)
gemcli music "Summer vibes" -s k-pop -o summer.mp4 -f video

# List all 16 style presets
gemcli music --list-styles
```

**Via MCP tools:**
```python
# Generate a track
mcp__gemini-web-mcp__music(action="generate", prompt="A jazz ballad about rain")

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

# Generate and auto-download
mcp__gemini-web-mcp__music(
    action="generate",
    prompt="Birthday song for Alex",
    style="birthday-roast",
    output_path="birthday.mp3"
)

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

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

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

---

## Workflow 6: Deep Research Pipeline

Goal: Run comprehensive research on a topic.

```bash
# Start research (creates plan, then executes)
gemcli research "What are the latest breakthroughs in quantum computing in 2026?"

# Save to file
gemcli research "Compare React, Vue, and Svelte for enterprise apps" -o framework_report.md
```

**Via MCP tools:**
```python
# Start research
mcp__gemini-web-mcp__research(action="start", query="AI agents architecture patterns")

# Check progress
mcp__gemini-web-mcp__research(action="status")
```

---

## Workflow 7: Gems Management

Goal: Create and use custom AI personas.

```bash
# List existing gems
gemcli gems list

# Create a code reviewer gem
gemcli gems create \
    --name "Senior Code Reviewer" \
    --description "Reviews code for quality, security, and performance" \
    --prompt "You are a senior software engineer conducting code reviews. Focus on:
1. Security vulnerabilities
2. Performance implications
3. Code readability and maintainability
4. Best practices and design patterns
Always provide specific, actionable feedback with code examples."

# Use the gem in chat (copy gem_id from create output)
gemcli chat "Review this Python function: def add(a,b): return a+b" --gem <gem_id>

# Delete a gem (always confirm with user first!)
gemcli gems delete <gem_id>
```

**Via MCP tools:**
```python
# List
mcp__gemini-web-mcp__gems(action="list")

# Create
mcp__gemini-web-mcp__gems(
    action="create",
    name="Writing Coach",
    system_prompt="You help improve writing clarity and style."
)

# Delete (always get user confirmation first!)
mcp__gemini-web-mcp__gems(action="delete", gem_id="abc123")
```

---

## Workflow 8: Multi-Profile Setup

Goal: Manage multiple Google accounts.

```bash
# Create profiles for different accounts
gemcli profile create personal
gemcli profile create work

# Authenticate each profile
gemcli login --profile personal
gemcli login --profile work

# Check all profiles
gemcli profile list

# Switch default profile
gemcli profile switch work

# Use specific profile for one-off command
gemcli chat "Hello" --profile personal

# If NotebookLM MCP is installed, shared profiles appear automatically
gemcli profile sources   # Shows which profiles come from NLM
```

---

## Workflow 9: MCP Setup for AI Tools

Goal: Configure gemini-web-mcp in your AI development tools.

```bash
# Check current status
gemcli setup list

# Add to specific tools
gemcli setup add claude-code        # Claude Code CLI
gemcli setup add claude-desktop     # Claude Desktop app
gemcli setup add cursor             # Cursor editor
gemcli setup add gemini-cli         # Google Gemini CLI
gemcli setup add windsurf           # Windsurf editor
gemcli setup add cline              # Cline agent
gemcli setup add antigravity        # Antigravity IDE

# Install skill documentation (teaches AI tools how to use gemcli)
gemcli skill install claude-code
gemcli skill install cursor

# Verify everything
gemcli doctor

# Remove from a tool if needed
gemcli setup remove cursor
gemcli skill uninstall cursor
```

**After setup:**
1. Restart the AI tool
2. The MCP server will be available as `gemini-web-mcp`
3. The skill teaches the AI tool about available commands and best practices

---

## Workflow 10: Diagnostic and Recovery

Goal: Troubleshoot and fix common issues.

```bash
# Full diagnostic
gemcli doctor --verbose

# If auth is broken:
gemcli login

# If Chrome login fails:
gemcli login --manual

# Check specific profile:
gemcli login --check --profile work

# Verify MCP clients:
gemcli setup list

# Verify skill installations:
gemcli skill list
```

---

## Workflow 11: Batch Operations with Extensions

Goal: Use Gemini's extensions (YouTube, Maps, etc.) in chat.

```bash
# Chat with YouTube extension
gemcli chat "@youtube Summarize this video: https://youtube.com/watch?v=..."

# Chat with Maps extension
gemcli chat "@maps Find restaurants near Times Square, NYC"

# Multiple extensions
gemcli chat "@youtube @maps Find travel guides for Tokyo and show nearby attractions"
```

**Via MCP tools:**
```python
mcp__gemini-web-mcp__chat(
    action="send",
    prompt="Summarize this video",
    extensions=["youtube"]
)
```
