Camoufox Cli

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)

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 "user@example.com"
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.

# Chain open + snapshot in one call
camoufox-cli open https://example.com && camoufox-cli snapshot -i

# Chain multiple interactions
camoufox-cli fill @e1 "user@example.com" && 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

# 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

camoufox-cli open https://example.com/signup
camoufox-cli snapshot -i
camoufox-cli fill @e1 "Jane Doe"
camoufox-cli fill @e2 "jane@example.com"
camoufox-cli select @e3 "California"
camoufox-cli check @e4
camoufox-cli click @e5
camoufox-cli snapshot -i  # Verify submission result

Data Extraction

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)

# 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

For long-lived accounts where the site also verifies device stability (not just the cookie), combine this with --persistent so the fingerprint stays fixed alongside the cookies — see the Persistent Identity section below.

Multiple Tabs

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

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)

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:

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:

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:

# 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

# 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:

camoufox-cli snapshot -i

Element Not Visible in Snapshot

# 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

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

Page Not Fully Loaded

# 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]    Persistent identity — reuse the same fingerprint + cookies across launches
                       (default path: ~/.camoufox-cli/profiles/<session>)
--proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
--no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")

Config file (optional). To avoid repeating flags, set defaults in ~/.camoufox-cli/config.json (override path with $CAMOUFOX_CLI_CONFIG): a default block applies to all sessions, and an optional sessions.<name> block layers extra overrides on top whenever you run --session <name> (the name is just whatever you pass to --session — sessions are never pre-registered). Settable keys: proxy, locale, geoip, persistent (true/false/path), headed, timeout, json. Command-line flags always win over the file. Config is read only when a session's daemon first launches.

{
  "default": { "persistent": true, "timeout": 3600 },
  "sessions": { "<your-session-name>": { "proxy": "socks5://127.0.0.1:1080", "locale": "zh-CN" } }
}

Persistent Identity

By default, every launch gets a fresh random fingerprint. Add --persistent [path] to reuse the same fingerprint + cookies across launches — fingerprint/OS/canvas+font seeds are frozen on first launch (delete the directory to reset); --locale and proxy-derived timezone/geolocation are stored but refreshed whenever you pass the flag; --proxy / --no-geoip are never stored, so pass them every launch.

Use it when the same device should see the same fingerprint across visits (account-bound tasks, parallel independent identities, or when cookies import/export alone isn't enough because the site also checks device stability). Skip it for one-off scraping or quick debugging.

# Parallel identities, each with its own fingerprint + cookies
camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://app.example.com

# Reset an identity: just remove the directory
rm -rf ~/.camoufox-cli/profiles/alice

Documentation

• camoufox-cli documentation -- Full README, setup guide, installation, and command reference

Command Reference

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

Navigation

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)

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)

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

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

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

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

Wait

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

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

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

JavaScript

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

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

Global Options

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] ... # Persistent identity — reuse the same fingerprint + cookies
                                     # across launches (default: ~/.camoufox-cli/profiles/<session>)
camoufox-cli --proxy <url> ...      # Proxy server (e.g. http://host:port or http://user:pass@host:port)
camoufox-cli --no-geoip ...         # Disable automatic GeoIP spoofing (auto-enabled with --proxy)
camoufox-cli --locale <tag> ...     # Force browser locale (e.g. "en-US" or "en-US,zh-CN")

--persistent in detail

Stores fingerprint, OS, canvas/font seeds, locale, and proxy-derived timezone/geolocation in <path>/camoufox-cli.json and reloads it on every launch with the same path. Fingerprint/OS/seeds are frozen — delete the directory to reset. --locale overwrites the stored locale when passed; --proxy + GeoIP re-derives timezone/geolocation each launch and writes back. --proxy and --no-geoip themselves are never stored. See the README for the full mental model.

Config file

Set defaults for the flags above in ~/.camoufox-cli/config.json (override path with $CAMOUFOX_CLI_CONFIG) instead of repeating them. A default block applies to every session; an optional sessions.<name> block layers extra overrides on top whenever you run --session <name> (the name is whatever you pass to --session — sessions are never pre-registered). Settable keys: proxy, locale, geoip, persistent (true/false/path), headed, timeout, json (session is CLI-only). Precedence: command-line flag > config sessions.<name> > config default > built-in default. Read only when a session's daemon first launches; a malformed file is ignored with a stderr warning.

{
  "default": { "persistent": true, "timeout": 3600 },
  "sessions": { "<your-session-name>": { "proxy": "socks5://127.0.0.1:1080", "locale": "zh-CN" } }
}

Snapshot and Refs

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

Related: commands.md for full command reference, SKILL.md for quick start.

Contents

• How Refs Work
• Snapshot Command
• Using Refs
• Ref Lifecycle
• Best Practices
• 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

# 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:

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

# Fill email input
camoufox-cli fill @e5 "user@example.com"

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

# 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

# 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

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

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:

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

5. Wait Before Snapshot on Slow Pages

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"

# 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

# 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

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