Grabbit CLI

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

Core Workflow

1. Authenticate: Ensure you are logged in.

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

2. Capture (Session): Always use --session <name> for isolation.

   # 1. Start session & Open URL
   grabbit browse --headed --session <name> open <url>
   
   # 2. Inspect & Interact
   grabbit browse --session <name> snapshot      # Get @e# refs
   grabbit browse --session <name> click @e1     # Click ref
   grabbit browse --session <name> fill @e2 "data"
   
   # 3. Verify
   grabbit browse --session <name> screenshot

3. Generate: Submit the capture with a verbose, example-rich prompt.

   grabbit save --session <name> "Detailed description. Example Input: 'X'. Example Output: { id: '123' }"

4. Poll: Wait for the result.

   grabbit check <task-id>

5. Integrate: Install the workflow as a local skill or use API keys for cURL.

   # Install as local agent skill
   grabbit add <workflow-id>
   
   # 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:

   export GRABBIT_API_KEY="<your-key>"

6. List Workflows: Find saved workflows (title/id/description).

   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.