name: grabbit
description: "Control the Grabbit CLI to record browser interactions (HAR) and generate API workflows. Use this skill when the user wants to: (1) Automate browser actions, (2) Capture web traffic for API analysis, (3) Create deterministic workflows from browsing sessions, or (4) Learn how to use the Grabbit CLI commands."

Grabbit CLI

Master the Grabbit CLI to convert browser interactions into stable API workflows.

Core Workflow

1. Authenticate: Ensure you are logged in.
   bash grabbit validate || grabbit auth

AI Quickstart (Minimal)

# 1) Auth
grabbit validate || grabbit auth

# 2) List workflows
grabbit workflows

# 3) Install the Grabbit skill in the current directory
grabbit skill install

# 4) Add a workflow as a skill
grabbit add <workflow-id>

# 5) Export API key for tools/agents
grabbit keys show
export GRABBIT_API_KEY="<your-key>"

1. Capture (Session): Always use --session <name> for isolation.
   ```bash
   # 1. Start session & Open URL
   grabbit browse --headed --session open

   2. Inspect & Interact

   grabbit browse --session snapshot # Get @e# refs
   grabbit browse --session click @e1 # Click ref
   grabbit browse --session fill @e2 "data"

   3. Verify

   grabbit browse --session screenshot
   ```

2. Generate: Submit the capture with a verbose, example-rich prompt.
   bash grabbit save --session <name> "Detailed description. Example Input: 'X'. Example Output: { id: '123' }"

3. Poll: Wait for the result.
   bash grabbit check <task-id>

4. Integrate: Install the workflow as a local skill or use API keys for cURL.
   ```bash
   # Install as local agent skill
   grabbit add

   Install the Grabbit skill in the current directory (recommended)

   grabbit skill install

   Manage integration keys

   grabbit keys list
   grabbit keys show
   Set the API key for tools/agents:bash
   export GRABBIT_API_KEY=""
   ```

5. List Workflows: Find saved workflows (title/id/description).
   bash grabbit workflows

Critical Best Practices

• Headed Mode: Use --headed for sites with bot protection (Cloudflare, 403s) or when visual debugging is needed.
• Snapshots: Run snapshot frequently to get stable @e# references (e.g., @e4) instead of fragile CSS selectors.
• API Keys: Use grabbit keys to manage tokens for production integrations. Scoped keys are recommended for specific workflows.
  • Recommended: Store the key in GRABBIT_API_KEY for tools and agents.
• Prompting: The backend agent needs concrete examples (strings seen on page, JSON shapes) to map HAR requests to workflow steps.
  • Bad: "Get prices."
  • Good: "Extract prices. Example: '$19.99'. Output: { price: number }."

Common Errors

• Waitlisted: Your account is not approved yet. Check the waitlist page or contact support.
• Unauthorized: Run grabbit auth, then retry.
• No active browser session: Start with grabbit browse --session <name> open <url> before grabbit save.
• No requests recorded: Interact with the page, then grabbit browse --session <name> snapshot.

Reference

For the full list of commands (cookies, storage, network, advanced locators), see cli_reference.md.