camoufox-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Anti-Detect Browser Automation with camoufox-cli

基于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.

camoufox-cli 基于Camoufox（反检测Firefox浏览器）构建，具备C++级别的指纹伪造能力：

```
navigator.webdriver
```
=
```
false
```
真实浏览器插件，随机化canvas/WebGL/音频指纹
真实Firefox UA字符串——可通过那些拦截Chromium自动化的网站的机器人检测

当目标网站存在机器人检测时，使用camoufox-cli替代agent-browser。

Core Workflow

核心工作流程

Every browser automation follows this pattern:

Navigate:
```
camoufox-cli open <url>
```
Snapshot:
```
camoufox-cli snapshot -i
```
(get element refs like
```
@e1
```
,
```
@e2
```
)
Interact: Use refs to click, fill, select
Re-snapshot: After navigation or DOM changes, get fresh refs

bash

camoufox-cli open https://example.com/form
camoufox-cli snapshot -i

所有浏览器自动化都遵循以下模式：

导航：
```
camoufox-cli open <url>
```
快照：
```
camoufox-cli snapshot -i
```
（获取元素引用，如
```
@e1
```
、
```
@e2
```
）
交互：使用引用进行点击、填写、选择操作
重新快照：导航或DOM变更后，获取新的元素引用

bash

camoufox-cli open https://example.com/form
camoufox-cli snapshot -i

Output: - textbox "Email" [ref=e1]

输出：- 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

undefined

camoufox-cli fill @e1 "user@example.com" camoufox-cli fill @e2 "password123" camoufox-cli click @e3 camoufox-cli snapshot -i # 检查操作结果

undefined

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

undefined

可以在单个Shell调用中使用

&&

链式执行命令。浏览器通过后台守护进程在命令之间保持会话，因此链式调用安全且比单独调用更高效。

bash

undefined

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

camoufox-cli open https://example.com && camoufox-cli screenshot page.png


**何时使用链式调用：** 当你不需要先读取中间命令的输出再继续时（例如打开+截图），使用`&&`。当你需要先解析输出再操作时（例如快照获取引用，再使用这些引用进行交互），请单独执行命令。

Essential Commands

核心命令

bash

undefined

bash

undefined

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

camoufox-cli open <url> # 导航到指定URL（需要时启动守护进程） camoufox-cli back # 返回上一页 camoufox-cli forward # 前进到下一页 camoufox-cli reload # 刷新页面 camoufox-cli url # 打印当前URL camoufox-cli title # 打印页面标题 camoufox-cli close # 关闭浏览器并停止守护进程 camoufox-cli close --all # 关闭所有会话

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

camoufox-cli snapshot # 获取页面完整ARIA树 camoufox-cli snapshot -i # 仅获取可交互元素（推荐使用） camoufox-cli snapshot -s "#selector" # 限定到指定CSS选择器范围

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

camoufox-cli click @e1 # 点击元素 camoufox-cli fill @e1 "text" # 清空并输入文本到输入框 camoufox-cli type @e1 "text" # 追加输入文本（不清空原有内容） camoufox-cli select @e1 "option" # 选择下拉菜单选项 camoufox-cli check @e1 # 切换复选框状态 camoufox-cli hover @e1 # 悬停在元素上 camoufox-cli press Enter # 按下键盘按键 camoufox-cli press "Control+a" # 按下组合键

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

camoufox-cli text @e1 # 获取元素的文本内容 camoufox-cli text body # 获取页面所有文本（使用CSS选择器） camoufox-cli eval "document.title" # 执行JavaScript代码

Capture

内容捕获

camoufox-cli screenshot # Screenshot to stdout (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

camoufox-cli screenshot # 将截图输出到标准输出（base64格式） camoufox-cli screenshot page.png # 将截图保存到文件 camoufox-cli screenshot --full p.png # 截取完整页面 camoufox-cli pdf output.pdf # 将页面保存为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

camoufox-cli scroll down # 向下滚动500px camoufox-cli scroll up # 向上滚动500px camoufox-cli scroll down 1000 # 向下滚动1000px camoufox-cli wait @e1 # 等待元素出现 camoufox-cli wait 2000 # 等待指定毫秒数 camoufox-cli wait --url "*/dashboard" # 等待URL匹配指定模式

Tabs

标签页相关

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

camoufox-cli tabs # 列出所有打开的标签页 camoufox-cli switch 2 # 切换到指定索引的标签页 camoufox-cli close-tab # 关闭当前标签页

Cookies & State

Cookie与状态管理

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

camoufox-cli cookies # 以JSON格式导出Cookie camoufox-cli cookies import file.json # 导入Cookie文件 camoufox-cli cookies export file.json # 导出Cookie到文件

Sessions

会话相关

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

camoufox-cli sessions # 列出所有活跃会话 camoufox-cli --session work open <url> # 使用命名会话 camoufox-cli close --all # 关闭所有会话

Setup

安装设置

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

undefined

camoufox-cli install # 下载Camoufox浏览器 camoufox-cli install --with-deps # 下载浏览器及系统依赖（Linux系统）

undefined

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 "jane@example.com"
camoufox-cli select @e3 "California"
camoufox-cli check @e4
camoufox-cli click @e5
camoufox-cli snapshot -i  # Verify submission result

bash

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  # 验证提交结果

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

bash

camoufox-cli open https://example.com/products
camoufox-cli snapshot -i
camoufox-cli text @e5                # 获取指定元素的文本
camoufox-cli eval "document.title"   # 通过JS获取页面标题
camoufox-cli screenshot results.png  # 可视化捕获内容

Cookie Management (Persist Login)

Cookie管理（持久化登录状态）

bash

undefined

bash

undefined

Login and export cookies

登录并导出Cookie

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

undefined

camoufox-cli open https://app.example.com camoufox-cli cookies import auth.json camoufox-cli reload

undefined

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

bash

camoufox-cli open https://site-a.com
camoufox-cli eval "window.open('https://site-b.com')"
camoufox-cli tabs                    # 列出所有标签页
camoufox-cli switch 1                # 切换到第二个标签页
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

bash

camoufox-cli --session s1 open https://site-a.com
camoufox-cli --session s2 open https://site-b.com
camoufox-cli sessions                # 列出两个会话
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

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.

当同时运行多个Agent或自动化任务时，请务必使用命名会话以避免冲突：

bash

camoufox-cli --session agent1 open https://site-a.com
camoufox-cli --session agent2 open https://site-b.com
camoufox-cli sessions                  # 查看活跃会话

完成操作后请务必关闭浏览器会话，避免进程泄漏：

bash

camoufox-cli close                     # 关闭默认会话
camoufox-cli --session agent1 close    # 关闭指定会话
camoufox-cli close --all               # 关闭所有会话

如果之前的会话未正常关闭，守护进程可能仍在运行。在开始新任务前，使用

camoufox-cli close

清理残留进程。

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

undefined

部分页面加载耗时较长，尤其是包含动态内容或大量JavaScript的页面。在获取快照前，请使用显式等待：

bash

undefined

Wait for a specific element to appear

等待指定元素出现

camoufox-cli wait @e1 camoufox-cli snapshot -i

Wait for a URL pattern (useful after redirects)

等待URL匹配指定模式（重定向后适用）

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.

camoufox-cli wait 3000 camoufox-cli snapshot -i

undefined

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

undefined

引用（

@e1

、

@e2

等）是临时标识符，在每次快照时按顺序分配。页面变更后，引用会失效。

以下情况后必须重新快照：

点击链接或按钮导致导航
表单提交后
动态内容加载（下拉菜单、模态框、懒加载内容）
滚动触发新内容加载

bash

undefined

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

camoufox-cli click @e5 # 导航到新页面 camoufox-cli snapshot -i # 必须重新快照 camoufox-cli click @e1 # 使用新的引用

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

camoufox-cli click @e1 # 打开下拉菜单 camoufox-cli snapshot -i # 查看下拉菜单项 camoufox-cli click @e7 # 选择菜单项

WRONG: using refs without snapshot

错误操作：未快照直接使用引用

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

camoufox-cli open https://example.com camoufox-cli click @e1 # 引用不存在！

WRONG: using old refs after navigation

错误操作：导航后使用旧引用

camoufox-cli click @e5 # Navigates away camoufox-cli click @e3 # STALE REF - wrong element!


For detailed ref documentation, see [references/snapshot-refs.md](references/snapshot-refs.md).

camoufox-cli click @e5 # 离开当前页面 camoufox-cli click @e3 # 引用已过期 - 操作错误元素！


关于引用的详细文档，请查看 [references/snapshot-refs.md](references/snapshot-refs.md)。

Troubleshooting

故障排查

"Ref @eN not found"

The ref was invalidated. Re-snapshot to get fresh refs:

bash

camoufox-cli snapshot -i

引用已失效。重新快照获取新引用：

bash

camoufox-cli snapshot -i

Element Not Visible in Snapshot

快照中未显示目标元素

bash

undefined

bash

undefined

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

undefined

camoufox-cli wait 2000 camoufox-cli snapshot -i

undefined

Too Many Elements in Snapshot

快照中元素过多

bash

undefined

bash

undefined

Scope to a specific container

限定到指定容器

camoufox-cli snapshot -s "#main-content" camoufox-cli snapshot -i -s "form.login"

undefined

camoufox-cli snapshot -s "#main-content" camoufox-cli snapshot -i -s "form.login"

undefined

Page Not Fully Loaded

页面未完全加载

bash

undefined

bash

undefined

Wait for URL pattern after redirect

重定向后等待URL匹配指定模式

camoufox-cli wait --url "*/dashboard" camoufox-cli snapshot -i

Wait a fixed duration as last resort

最后手段：等待固定时长

camoufox-cli wait 3000 camoufox-cli snapshot -i

undefined

camoufox-cli wait 3000 camoufox-cli snapshot -i

undefined

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 directory

--session <name>       命名会话（默认："default"）
--headed               显示浏览器窗口（默认：无头模式）
--timeout <seconds>    守护进程空闲超时时间（默认：1800）
--json                 以JSON格式输出（替代人类可读格式）
--persistent <path>    使用持久化浏览器配置文件目录

Deep-Dive Documentation

深度文档

Reference	When to Use
references/snapshot-refs.md	Ref lifecycle, invalidation rules, troubleshooting
references/commands.md	Full command reference with all options

参考文档	使用场景
references/snapshot-refs.md	引用生命周期、失效规则、故障排查
references/commands.md	完整命令参考及所有选项