Glitch CLI

Command-line tool for capturing UI bugs, generating AI-ready context packs, and integrating with Cursor, Claude, and Windsurf via MCP.

One command. No extension. No manual MCP setup.

glitch snapshot "https://example.com"

Browser opens → you click elements → pack is saved → use contextpacks://<packId> in your AI agent.

Install

# Global install (recommended)
npm install -g glitch-cli

# Or run via npx
npx glitch-cli snapshot "https://example.com"

Requirements: Node.js 18+, Chromium (installed automatically with Playwright on first run)

Quick Start

1. Capture a page (interactive picker):

   glitch snapshot "https://example.com"

2. Save locally (default) or upload to cloud:

   glitch snapshot "https://example.com" --local
   glitch snapshot "https://example.com" --cloud   # requires api_key in config

3. Use the pack — after capture, you'll get:

   Resource URI: contextpacks://pack_xxxxx
   Next step: paste this URI into Cursor/Claude with the Glitch MCP server enabled.

Commands

| Command | Description | |--------|-------------| | glitch snapshot <url> | Capture snapshot shorthand | | glitch record <url> | Capture recorder shorthand | | glitch capture | Capture page elements (snapshot or recorder mode) | | glitch packs list | List cloud packs (/v1/packs) | | glitch packs show <packRef> | Show summary metadata for one pack | | glitch packs pull <packRef> | Alias for glitch pull <packRef> | | glitch pull <packId> | Download a cloud pack bundle and unpack locally | | glitch prompt generate <packRef> | Generate AI-ready prompt text | | glitch prompt copy <packRef> | Copy generated prompt text to clipboard | | glitch workspace init [path] | Initialize project config, register workspace, and set current (default) | | glitch workspace add [path] --name <name> | Register existing project root as workspace | | glitch workspace list | List saved workspaces | | glitch workspace use <name\|path> | Set current workspace | | glitch workspace current | Show current workspace | | glitch login | Authenticate via browser handoff and store API key | | glitch logout | Clear stored API key from config | | glitch whoami | Show current auth/account identity | | glitch keys list | List API keys for current user | | glitch keys create [label] | Create a new API key (plaintext shown once) | | glitch keys revoke <keyId> | Revoke an API key | | glitch connect <target> | Write MCP config for cursor, claude, or windsurf | | glitch init | Create ~/.glitch/config.json with defaults | | glitch config set <key> <value> | Update a config value | | glitch config get <key> | Read a config value | | glitch config list | List effective config values | | glitch doctor | Run local/cloud diagnostics | | glitch status | Show cloud URL, auth, and usage | | glitch help | Show help |

Capture Reference

glitch capture [url] [options]

Required: Provide a URL either as positional <url> or --url <url>

Options:

| Option | Description | Default | |--------|-------------|---------| | --mode snapshot\|recorder | Snapshot (one-shot) or recorder (record interactions) | snapshot | | --bug-type <type> | animation, layout-shift, overlap-zindex, color-visibility, overflow-clipping, other | — | | --selector <css> | Skip picker, capture selector directly (repeatable) | — | | --multi | Allow picking multiple elements (press Enter in terminal to finish) | — | | --headless | No browser window (requires --selector) | — | | --cloud | Upload to MCP server | — | | --local | Save to local directory | default | | --out <dir> | Local output directory | ~/.glitch/context-packs | | --prompt <text> | Attach prompt/problem statement to pack | — | | --prompt-tag <alias>=<css> | Bind prompt alias to selector (repeatable) | — | | --prompt-pick <alias> | Pick a prompt alias target in browser (repeatable) | — | | --activate | Attempt to add uploaded pack to Active Issues | — | | --no-activate | Skip Active Issues activation | — | | --screenshot <path> | Save screenshot | — | | --wait <mode> | domcontentloaded, load, networkidle | domcontentloaded | | --no-close | Keep browser open after capture | — |

Examples:

# Snapshot with picker
glitch snapshot "https://example.com"

# Recorder, multi-element, save locally
glitch record "https://example.com" --multi --local

# Headless with selectors
glitch capture "https://example.com" --selector ".card" --selector "button" --headless --cloud

Configuration

Config file: ~/.glitch/config.json

{
  "default_destination": "local",
  "local_pack_dir": "~/.glitch/context-packs",
  "cloud_url": "https://your-mcp-server.example.com",
  "api_key": "glk_live_..."
}

Config keys:

• default_destination — local or cloud
• local_pack_dir — Directory for local packs
• cloud_url — MCP server URL
• api_key — API key for cloud uploads (config get/list redact it by default)

Initialize config: glitch init
Set a value: glitch config set api_key glk_live_xxx Get a value: glitch config get cloud_url
Get the API key status: glitch config get api_key
Reveal the full API key intentionally: glitch config get api_key --show-secret
List all values: glitch config list or glitch config list --json

Workspace

Workspace registry file: ~/.glitch/workspaces.json

# Initialize project config + register workspace + set current (default behavior)
glitch workspace init ./my-app

# Keep project config setup but skip workspace registry changes
glitch workspace init ./my-app --no-register

# Register workspace without switching current workspace
glitch workspace init ./my-app --name my-app --no-use

# Register existing root without rewriting .glitch/project.json
glitch workspace add ./my-app --name my-app

# List and inspect current workspace
glitch workspace list
glitch workspace list --json
glitch workspace current
glitch workspace current --json

# Switch current workspace by name or path
glitch workspace use my-app
glitch workspace use ./my-app

Pull

Download a cloud pack and unpack it locally:

glitch pull <packId> [options]
glitch packs pull <packId> [options]

Options: --mode slim|full, --format dir|bundle, --to <path>

Packs

glitch packs list [--json] [--host <hostname>] [--source <snapshot|recorder>] [--active]
glitch packs show <packRef> [--mode slim|full] [--workspace <name|path>] [--json]
glitch packs pull <packRef> [--workspace <name|path>] [options]

<packRef> supports:

• cloud pack ID
• local pulled directory pack path
• local bundle JSON path

Prompt

glitch prompt generate <packRef> [options]
glitch prompt copy <packRef> [options]

generate options:

• --target <cursor|claude|copilot|chatgpt>
• --framework <auto|react|vue|angular|svelte>
• --style <concise|detailed>
• --include-code / --no-code
• --mode <slim|full>
• --workspace <name|path>
• --json (generate only)

Auth & Keys

glitch login
glitch logout
glitch whoami [--json]
glitch keys list [--json]
glitch keys create [label] [--json]
glitch keys revoke <keyId> [--yes]

glitch login starts Firebase handoff auth in your browser and stores the resulting API key in ~/.glitch/config.json.

Connect

Generate MCP configuration for your editor:

glitch connect cursor --gitignore  # Adds .cursor/ to the repo .gitignore, then writes .cursor/mcp.json
glitch connect cursor --template   # Writes a placeholder without a real key
glitch connect claude              # Prints Claude connector instructions with redacted auth output
glitch connect claude --show-token # Prints the live bearer token for manual paste
glitch connect windsurf            # Writes to Windsurf config

Repo-scoped Cursor config refuses to write a real API key unless .cursor/ is already gitignored or you pass --gitignore. Claude remote setup prints Authorization: Bearer [REDACTED] by default; use --show-token only when you intentionally need the live token in the terminal.

Build from Source

git clone https://github.com/glitch-cli/glitch-cli.git
cd glitch-cli
npm install
npx playwright install chromium   # Browser binary for capture
npm run build

Then run: node cli/dist/glitch.js help

Development

# Run tests
npm test

# Build
npm run build

Project Structure

glitch-cli/
├── cli/                    # CLI entry points and capture logic
│   ├── glitch.ts           # Main entry (capture, pull, connect, init, doctor, status)
│   ├── capture.ts          # Capture workflow
│   ├── capture-inject.ts   # Browser-injected picker/capture (IIFE)
│   ├── pull.ts             # Pull command
│   ├── connect.ts          # Connect command
│   └── bundle.ts           # Bundle utilities
├── src/lib/                # Shared libraries
│   ├── capture/            # Element capture
│   ├── context-pack/       # Pack building, delta, summary
│   ├── security/           # Redaction
│   ├── analysis/           # Bug patterns
│   └── framework/          # Framework detection
├── tests/                  # Unit and integration tests
└── cli/dist/               # Built output (glitch.js, capture-inject.js)

License

MIT