Skill: bin-huang/camoufox-cli (version 1.0.0)

--- name: camoufox-cli description: Anti-detect browser automation CLI & Skills for AI agents. Use when the user needs to interact with websites with bot detection, CAPTCHAs, or anti-bot blocks, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task that requires bypassing fingerprint checks. --- # Anti-Detect Browser Automation with camoufox-cli ## What Makes This Different camoufox-cli is built on Camoufox (anti-detect Firefox) with C++-level fingerprint spoofing: - `navigator.webdriver` = `false` - Real browser plugins, randomized canvas/WebGL/audio fingerprints - Real Firefox UA string -- passes bot detection on sites that block Chromium automation Use camoufox-cli instead of agent-browser when the target site has bot detection. ## Core Workflow Every browser automation follows this pattern: 1. **Navigate**: `camoufox-cli open <url>` 2. **Snapshot**: `camoufox-cli snapshot -i` (get element refs like `@e1`, `@e2`) 3. **Interact**: Use refs to click, fill, select 4. **Re-snapshot**: After navigation or DOM changes, get fresh refs 5. **Close**: `camoufox-cli close` (close the browser when the entire task is fully complete; keep it open if the user may have follow-up instructions) ```bash camoufox-cli open https://example.com/form camoufox-cli snapshot -i # Output: - textbox "Email" [ref=e1] # - textbox "Password" [ref=e2] # - button "Submit" [ref=e3] camoufox-cli fill @e1 "[REDACTED_SECRET]" camoufox-cli fill @e2 "password123" camoufox-cli click @e3 camoufox-cli snapshot -i # Check result ``` ## Command Chaining Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls. ```bash # Chain open + snapshot in one call camoufox-cli open https://example.com && camoufox-cli snapshot -i # Chain multiple interactions camoufox-cli fill @e1 "[REDACTED_SECRET]" && camoufox-cli fill @e2 "password123" && camoufox-cli click @e3 # Navigate and capture camoufox-cli open https://example.com && camoufox-cli screenshot page.png ``` **When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs). ## Essential Commands ```bash # Navigation camoufox-cli open <url> # Navigate to URL (starts daemon if needed) camoufox-cli back # Go back camoufox-cli forward # Go forward camoufox-cli reload # Reload page camoufox-cli url # Print current URL camoufox-cli title # Print page title camoufox-cli close # Close browser and stop daemon camoufox-cli close --all # Close all sessions # Snapshot camoufox-cli snapshot # Full aria tree of page camoufox-cli snapshot -i # Interactive elements only (recommended) camoufox-cli snapshot -s "#selector" # Scope to CSS selector # Interaction (use @refs from snapshot) camoufox-cli click @e1 # Click element camoufox-cli fill @e1 "text" # Clear + type into input camoufox-cli type @e1 "text" # Type without clearing (append) camoufox-cli select @e1 "option" # Select dropdown option camoufox-cli check @e1 # Toggle checkbox camoufox-cli hover @e1 # Hover over element camoufox-cli press Enter # Press keyboard key camoufox-cli press "Control+a" # Key combination # Data Extraction camoufox-cli text @e1 # Get text content of element camoufox-cli text body # Get all page text (CSS selector) camoufox-cli eval "document.title" # Execute JavaScript # Capture camoufox-cli screenshot # Screenshot as JSON {"base64": "..."} camoufox-cli screenshot page.png # Screenshot to file camoufox-cli screenshot --full p.png # Full page screenshot camoufox-cli pdf output.pdf # Save page as PDF # Scroll & Wait camoufox-cli scroll down # Scroll down 500px camoufox-cli scroll up # Scroll up 500px camoufox-cli scroll down 1000 # Scroll down 1000px camoufox-cli wait @e1 # Wait for element to appear camoufox-cli wait 2000 # Wait milliseconds camoufox-cli wait --url "*/dashboard" # Wait for URL pattern # Tabs camoufox-cli tabs # List open tabs camoufox-cli switch 2 # Switch to tab by index camoufox-cli close-tab # Close current tab # Cookies & State camoufox-cli cookies # Dump cookies as JSON camoufox-cli cookies import file.json # Import cookies camoufox-cli cookies export file.json # Export cookies # Sessions camoufox-cli sessions # List active sessions camoufox-cli --session work open <url> # Use named session camoufox-cli close --all # Close all sessions # Setup camoufox-cli install # Download Camoufox browser camoufox-cli install --with-deps # Download browser + system libs (Linux) ``` ## Common Patterns ### Form Submission ```bash camoufox-cli open https://example.com/signup camoufox-cli snapshot -i camoufox-cli fill @e1 "Jane Doe" camoufox-cli fill @e2 "[REDACTED_SECRET]" camoufox-cli select @e3 "California" camoufox-cli check @e4 camoufox-cli click @e5 camoufox-cli snapshot -i # Verify submission result ``` ### Data Extraction ```bash camoufox-cli open https://example.com/products camoufox-cli snapshot -i camoufox-cli text @e5 # Get specific element text camoufox-cli eval "document.title" # Get page title via JS camoufox-cli screenshot results.png # Visual capture ``` ### Cookie Management (Persist Login) ```bash # Login and export cookies camoufox-cli open https://app.example.com/login camoufox-cli snapshot -i camoufox-cli fill @e1 "user" camoufox-cli fill @e2 "pass" camoufox-cli click @e3 camoufox-cli cookies export auth.json # Restore in future session camoufox-cli open https://app.example.com camoufox-cli cookies import auth.json camoufox-cli reload ``` ### Multiple Tabs ```bash camoufox-cli open https://site-a.com camoufox-cli eval "window.open('https://site-b.com')" camoufox-cli tabs # List tabs camoufox-cli switch 1 # Switch to second tab camoufox-cli snapshot -i ``` ### Parallel Sessions ```bash camoufox-cli --session s1 open https://site-a.com camoufox-cli --session s2 open https://site-b.com camoufox-cli sessions # List both camoufox-cli --session s1 snapshot -i camoufox-cli --session s2 snapshot -i ``` ### Visual Browser (Debugging) ```bash camoufox-cli --headed open https://example.com camoufox-cli snapshot -i camoufox-cli screenshot debug.png ``` ## Session Management and Cleanup When running multiple agents or automations concurrently, always use named sessions to avoid conflicts: ```bash camoufox-cli --session agent1 open https://site-a.com camoufox-cli --session agent2 open https://site-b.com camoufox-cli sessions # Check active sessions ``` Always close your browser session when done to avoid leaked processes: ```bash camoufox-cli close # Close default session camoufox-cli --session agent1 close # Close specific session camoufox-cli close --all # Close all sessions ``` If a previous session was not closed properly, the daemon may still be running. Use `camoufox-cli close` to clean it up before starting new work. ## Timeouts and Slow Pages Some pages take time to fully load, especially those with dynamic content or heavy JavaScript. Use explicit waits before taking a snapshot: ```bash # Wait for a specific element to appear camoufox-cli wait @e1 camoufox-cli snapshot -i # Wait for a URL pattern (useful after redirects) camoufox-cli wait --url "*/dashboard" camoufox-cli snapshot -i # Wait a fixed duration as a last resort camoufox-cli wait 3000 camoufox-cli snapshot -i ``` When dealing with slow pages, always wait before snapshotting. If you snapshot too early, elements may be missing from the output. ## Ref Lifecycle (Important) Refs (`@e1`, `@e2`, etc.) are **temporary identifiers** assigned by sequential numbering during each snapshot. They are invalidated when the page changes. **Always re-snapshot after:** - Clicking links or buttons that navigate - Form submissions - Dynamic content loading (dropdowns, modals, lazy-loaded content) - Scrolling that triggers new content ```bash # CORRECT: re-snapshot after navigation camoufox-cli click @e5 # Navigates to new page camoufox-cli snapshot -i # MUST re-snapshot camoufox-cli click @e1 # Use new refs # CORRECT: re-snapshot after dynamic changes camoufox-cli click @e1 # Opens dropdown camoufox-cli snapshot -i # See dropdown items camoufox-cli click @e7 # Select item # WRONG: using refs without snapshot camoufox-cli open https://example.com camoufox-cli click @e1 # Ref doesn't exist yet! # WRONG: using old refs after navigation camoufox-cli click @e5 # Navigates away camoufox-cli click @e3 # STALE REF - wrong element! ``` Always take a fresh snapshot before interacting with elements after navigation or page changes. ## Troubleshooting ### "Ref @eN not found" The ref was invalidated. Re-snapshot to get fresh refs: ```bash camoufox-cli snapshot -i ``` ### Element Not Visible in Snapshot ```bash # Scroll down to reveal element camoufox-cli scroll down 1000 camoufox-cli snapshot -i # Or wait for dynamic content camoufox-cli wait 2000 camoufox-cli snapshot -i ``` ### Too Many Elements in Snapshot ```bash # Scope to a specific container camoufox-cli snapshot -s "#main-content" camoufox-cli snapshot -i -s "form.login" ``` ### Page Not Fully Loaded ```bash # Wait for URL pattern after redirect camoufox-cli wait --url "*/dashboard" camoufox-cli snapshot -i # Wait a fixed duration as last resort camoufox-cli wait 3000 camoufox-cli snapshot -i ``` ## Global Flags ``` --session <name> Named session (default: "default") --headed Show browser window (default: headless) --timeout <seconds> Daemon idle timeout (default: 1800) --json Output as JSON instead of human-readable --persistent [path] Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>) --proxy <url> Proxy server (e.g. http://host:port or [REDACTED_SECRET]) ``` ## Documentation - [camoufox-cli documentation](https://github.com/Bin-Huang/camoufox-cli) -- Full README, setup guide, installation, and command reference

path: references/commands.md
content: # Command Reference

Complete reference for all camoufox-cli commands. For quick start and common patterns, see SKILL.md.

## Navigation

```bash
camoufox-cli open <url>              # Navigate to URL (starts daemon if needed)
                                     # Auto-prepends https:// if no protocol given
camoufox-cli back                    # Go back
camoufox-cli forward                 # Go forward
camoufox-cli reload                  # Reload page
camoufox-cli url                     # Print current URL
camoufox-cli title                   # Print page title
camoufox-cli close                   # Close browser and stop daemon
camoufox-cli close --all             # Close all sessions
```

## Snapshot (Page Analysis)

```bash
camoufox-cli snapshot                # Full accessibility tree
camoufox-cli snapshot -i             # Interactive elements only (recommended)
camoufox-cli snapshot -s "#main"     # Scope to CSS selector
camoufox-cli snapshot -i -s "form"   # Interactive + scoped
```

## Interactions (use @refs from snapshot)

```bash
camoufox-cli click @e1               # Click element
camoufox-cli fill @e1 "text"         # Clear and type
camoufox-cli type @e1 "text"         # Type without clearing (append)
camoufox-cli select @e1 "value"      # Select dropdown option
camoufox-cli check @e1               # Toggle checkbox
camoufox-cli hover @e1               # Hover over element
camoufox-cli press Enter             # Press key
camoufox-cli press "Control+a"       # Key combination
```

## Get Information

```bash
camoufox-cli text @e1                # Get element text (by ref)
camoufox-cli text body               # Get all page text (by CSS selector)
camoufox-cli url                     # Get current URL
camoufox-cli title                   # Get page title
camoufox-cli eval "document.title"   # Run JavaScript expression
```

## Screenshots and PDF

```bash
camoufox-cli screenshot              # Screenshot to stdout (base64)
camoufox-cli screenshot page.png     # Save to file
camoufox-cli screenshot --full p.png # Full page screenshot
camoufox-cli pdf output.pdf          # Save page as PDF
```

## Scroll

```bash
camoufox-cli scroll down             # Scroll down 500px (default)
camoufox-cli scroll up               # Scroll up 500px
camoufox-cli scroll down 1000        # Scroll down 1000px
```

## Wait

```bash
camoufox-cli wait @e1                # Wait for element to appear
camoufox-cli wait 2000               # Wait milliseconds
camoufox-cli wait --url "*/dashboard" # Wait for URL pattern
```

## Tabs

```bash
camoufox-cli tabs                    # List open tabs
camoufox-cli switch 2                # Switch to tab by index
camoufox-cli close-tab               # Close current tab
```

## Cookies

```bash
camoufox-cli cookies                 # Dump cookies as JSON
camoufox-cli cookies import file.json # Import cookies from file
camoufox-cli cookies export file.json # Export cookies to file
```

## Sessions

```bash
camoufox-cli sessions                # List active sessions
camoufox-cli --session <name> <cmd>  # Run command in named session
camoufox-cli close --all             # Close all sessions
```

## JavaScript

```bash
camoufox-cli eval "document.title"   # Simple expression
camoufox-cli eval "document.querySelectorAll('img').length"
```

For complex JavaScript with nested quotes, use shell escaping carefully or pipe via stdin.

## Setup

```bash
camoufox-cli install                 # Download Camoufox browser
camoufox-cli install --with-deps     # Download browser + system libs (Linux)
```

## Global Options

```bash
camoufox-cli --session <name> ...    # Isolated browser session
camoufox-cli --headed ...            # Show browser window (not headless)
camoufox-cli --json ...              # JSON output for parsing
camoufox-cli --timeout <seconds> ... # Daemon idle timeout (default: 1800)
camoufox-cli --persistent [path] ... # Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
camoufox-cli --proxy <url> ...      # Proxy server (e.g. http://host:port or [REDACTED_SECRET])
```


path: references/snapshot-refs.md
content: # Snapshot and Refs

Compact element references for AI agents to interact with page elements efficiently.

**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.

## Contents

- [How Refs Work](#how-refs-work)
- [Snapshot Command](#the-snapshot-command)
- [Using Refs](#using-refs)
- [Ref Lifecycle](#ref-lifecycle)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

## How Refs Work

Traditional approach:
```
Full DOM/HTML -> AI parses -> CSS selector -> Action (~3000-5000 tokens)
```

camoufox-cli approach:
```
Compact aria snapshot -> @refs assigned -> Direct interaction (~200-400 tokens)
```

Refs are sequential numbers (`@e1`, `@e2`, ...) assigned to elements during each snapshot based on DOM traversal order. The same element may get different refs across snapshots if the page content changes.

## The Snapshot Command

```bash
# Basic snapshot (shows full page structure)
camoufox-cli snapshot

# Interactive snapshot (-i flag) - RECOMMENDED
camoufox-cli snapshot -i

# Scoped to a specific container
camoufox-cli snapshot -s "#main-content"
camoufox-cli snapshot -i -s "form.login"
```

### Snapshot Output Format

```
- heading "Example Domain" [ref=e1]
- navigation
  - link "Home" [ref=e2]
  - link "Products" [ref=e3]
  - link "About" [ref=e4]
- button "Sign In" [ref=e5]
- main
  - heading "Welcome" [ref=e6]
  - textbox "Email" [ref=e7]
  - textbox "Password" [ref=e8]
  - button "Log In" [ref=e9]
- contentinfo
  - link "Privacy Policy" [ref=e10]
```

With `-i` (interactive only), non-interactive elements are filtered out:

```
- link "Home" [ref=e1]
- link "Products" [ref=e2]
- link "About" [ref=e3]
- button "Sign In" [ref=e4]
- textbox "Email" [ref=e5]
- textbox "Password" [ref=e6]
- button "Log In" [ref=e7]
- link "Privacy Policy" [ref=e8]
```

## Using Refs

Once you have refs, interact directly:

```bash
# Click the "Sign In" button
camoufox-cli click @e4

# Fill email input
camoufox-cli fill @e5 "[REDACTED_SECRET]"

# Fill password
camoufox-cli fill @e6 "password123"

# Submit the form
camoufox-cli click @e7
```

## Ref Lifecycle

**IMPORTANT**: Refs are invalidated when the page changes!

Refs are assigned by sequential numbering during each snapshot. They are tied to that specific page state. After any change to the page, old refs may point to wrong elements or not exist at all.

```bash
# Get initial snapshot
camoufox-cli snapshot -i
# - button "Next" [ref=e1]

# Click triggers page change
camoufox-cli click @e1

# MUST re-snapshot to get new refs!
camoufox-cli snapshot -i
# - heading "Page 2" [ref=e1]  <- Different element now!
```

### What Invalidates Refs

- **Navigation**: clicking links, form submissions, redirects
- **Dynamic content**: dropdowns opening, modals appearing, AJAX updates
- **Scrolling**: if it triggers lazy loading of new content
- **JavaScript**: any DOM mutation that changes element order

### What Happens with Stale Refs

When you use a ref without re-snapshotting after a page change:
- The ref may point to a **different element** (wrong click target)
- The ref may **not exist** (error)
- The action may **silently succeed on the wrong element**

This is the most common source of automation errors. When in doubt, re-snapshot.

## Best Practices

### 1. Always Snapshot Before Interacting

```bash
# CORRECT
camoufox-cli open https://example.com
camoufox-cli snapshot -i          # Get refs first
camoufox-cli click @e1            # Use ref

# WRONG
camoufox-cli open https://example.com
camoufox-cli click @e1            # Ref doesn't exist yet!
```

### 2. Re-Snapshot After Navigation

```bash
camoufox-cli click @e5            # Navigates to new page
camoufox-cli snapshot -i          # Get new refs
camoufox-cli click @e1            # Use new refs
```

### 3. Re-Snapshot After Dynamic Changes

```bash
camoufox-cli click @e1            # Opens dropdown
camoufox-cli snapshot -i          # See dropdown items
camoufox-cli click @e7            # Select item
```

### 4. Scope Snapshots on Complex Pages

For pages with many elements, scope the snapshot to reduce noise:

```bash
camoufox-cli snapshot -i -s "#login-form"
camoufox-cli snapshot -i -s ".product-list"
```

### 5. Wait Before Snapshot on Slow Pages

```bash
camoufox-cli open https://slow-site.com
camoufox-cli wait 3000            # Wait for content to load
camoufox-cli snapshot -i          # Now snapshot
```

## Troubleshooting

### "Ref @eN not found"

```bash
# Ref was invalidated - re-snapshot
camoufox-cli snapshot -i
```

Common causes:
- Page navigated since last snapshot
- Dynamic content changed the DOM
- Never took a snapshot after opening the page

### Element Not Visible in Snapshot

```bash
# Scroll down to reveal element
camoufox-cli scroll down 1000
camoufox-cli snapshot -i

# Or wait for dynamic content
camoufox-cli wait 2000
camoufox-cli snapshot -i
```

### Too Many Elements

```bash
# Scope to specific container
camoufox-cli snapshot -i -s "#main"

# Or use text extraction for content-only
camoufox-cli text body
```

### Duplicate Elements (Same Role + Name)

When multiple elements have the same role and name (e.g., two "Submit" buttons), each gets a unique ref. The snapshot shows `[nth=N]` for disambiguation:

```
- button "Submit" [ref=e3]
- button "Submit" [ref=e7] [nth=1]
```

Both refs work independently. Use the one that corresponds to the element you need.


Security scan verdicts — ClawScan: malicious | static analysis: clean | VirusTotal:  | SkillSpector:  ()