camoufox-cli 0.1.5

Anti-detect browser CLI for AI agents, powered by Camoufox

camoufox-cli

Anti-detect headless browser automation CLI for AI agents, powered by Camoufox.

Camoufox is a stealthy Firefox fork with C++-level fingerprint spoofing. It defeats bot detection by masking navigator.webdriver, randomizing canvas/WebGL/audio fingerprints, and injecting real browser plugins. However, Camoufox only provides a Python API. AI agents like OpenClaw or Claude Code would need to generate Python glue code to use it, which is fragile, wastes tokens, and distracts the agent from its actual task.

camoufox-cli bridges this gap by wrapping Camoufox into a stateless CLI. A background daemon manages the browser instance and ref registry, so each command is a simple shell call: snapshot the accessibility tree, interact by ref, repeat. Any AI agent that can invoke shell commands can use Camoufox, no Python glue code generation needed.

Install

npm install -g camoufox-cli
camoufox-cli install              # Download browser

Or with pip:

pipx install camoufox-cli
camoufox-cli install              # Download browser

On Linux, install system dependencies with:

camoufox-cli install --with-deps

Quick Start

camoufox-cli open https://example.com    # Launch browser & navigate
camoufox-cli snapshot -i                  # Interactive elements only
# - link "More information..." [ref=e1]
camoufox-cli click @e1                    # Click by ref
camoufox-cli close                        # Done

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

Snapshot

camoufox-cli snapshot                     # Full accessibility tree
camoufox-cli snapshot -i                  # Interactive elements only
camoufox-cli snapshot -s "css-selector"   # Scoped to CSS selector

Output format:

- heading "Example Domain" [level=1] [ref=e1]
- paragraph [ref=e2]
  - link "More information..." [ref=e3]

Interaction

camoufox-cli click @e1                    # Click element
camoufox-cli fill @e3 "search query"      # Clear + type into input
camoufox-cli type @e3 "append text"       # Type without clearing
camoufox-cli select @e5 "option text"     # Select dropdown option
camoufox-cli check @e6                    # Toggle checkbox
camoufox-cli hover @e2                    # 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
camoufox-cli eval "document.title"        # Execute JavaScript
camoufox-cli screenshot                   # Screenshot (base64 to stdout)
camoufox-cli screenshot page.png          # Screenshot to file
camoufox-cli screenshot --full page.png   # Full page screenshot

Scroll & Wait

camoufox-cli scroll down                  # Scroll down 500px
camoufox-cli scroll up 1000               # Scroll up 1000px
camoufox-cli wait 2000                    # Wait milliseconds
camoufox-cli wait @e1                     # Wait for element to appear
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

Sessions

camoufox-cli sessions                     # List active sessions
camoufox-cli --session work open <url>    # Use named session
camoufox-cli close --all                  # Close all sessions

Cookies

camoufox-cli cookies                      # Dump cookies as JSON
camoufox-cli cookies import file.json     # Import cookies
camoufox-cli cookies export file.json     # Export cookies

Flags

--session <name>       Named session (default: "default")
--headed               Show browser window (default: headless)
--timeout <seconds>    Daemon idle timeout (default: 1800)
--json                 Output as JSON
--persistent <path>    Use persistent browser profile directory

Architecture

CLI (camoufox-cli)  ──Unix socket──▶  Daemon (Python)  ──Playwright──▶  Camoufox (Firefox)

The CLI sends JSON commands to a long-running daemon process via Unix socket. The daemon manages the Camoufox browser instance and maintains the ref registry between commands. The daemon auto-starts on the first command and auto-stops after 30 minutes of inactivity.

License

MIT