camoufox-cli 0.7.6__tar.gz → 0.8.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/.gitignore +1 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/PKG-INFO +32 -9
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/README.md +31 -8
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/pyproject.toml +1 -1
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/cli.py +29 -2
- camoufox_cli-0.8.0/src/camoufox_cli/guide/commands.md +153 -0
- camoufox_cli-0.8.0/src/camoufox_cli/guide/snapshot-refs.md +221 -0
- camoufox_cli-0.8.0/src/camoufox_cli/guide/usage.md +402 -0
- camoufox_cli-0.8.0/src/camoufox_cli/skill.py +62 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/LICENSE +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/__init__.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/__main__.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/browser.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/commands.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/config.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/identity.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/install.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/protocol.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/proxy.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/refs.py +0 -0
- {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/server.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: camoufox-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.0
|
|
4
4
|
Summary: Anti-detect browser CLI & Skills for AI agents, powered by Camoufox
|
|
5
5
|
Project-URL: Homepage, https://github.com/Bin-Huang/camoufox-cli
|
|
6
6
|
Project-URL: Repository, https://github.com/Bin-Huang/camoufox-cli
|
|
@@ -22,8 +22,28 @@ Description-Content-Type: text/markdown
|
|
|
22
22
|
|
|
23
23
|
# camoufox-cli
|
|
24
24
|
|
|
25
|
+
[](https://www.npmjs.com/package/camoufox-cli)
|
|
26
|
+
[](https://pypi.org/project/camoufox-cli/)
|
|
27
|
+
[](https://www.npmjs.com/package/camoufox-cli)
|
|
28
|
+
[](LICENSE)
|
|
29
|
+
|
|
25
30
|
Anti-detect browser CLI & Skills for AI agents, powered by [Camoufox](https://github.com/daijro/camoufox).
|
|
26
31
|
|
|
32
|
+
Playwright and Puppeteer leak that they're automated — headless flags, canvas and
|
|
33
|
+
WebGL fingerprints, missing fonts, mismatched screen metrics. Camoufox patches those
|
|
34
|
+
at the C++ level, so the browser itself looks like a normal Firefox install.
|
|
35
|
+
|
|
36
|
+
That's the fingerprint layer only. Detection that keys on IP reputation, request rate,
|
|
37
|
+
or behavior still applies — pair it with `--proxy` and sane pacing.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
camoufox-cli open https://example.com # Launch browser & navigate
|
|
41
|
+
camoufox-cli snapshot -i # Interactive elements only
|
|
42
|
+
# - link "More information..." [ref=e1]
|
|
43
|
+
camoufox-cli click @e1 # Click by ref
|
|
44
|
+
camoufox-cli close # Done
|
|
45
|
+
```
|
|
46
|
+
|
|
27
47
|
### Highlights
|
|
28
48
|
|
|
29
49
|
- C++-level fingerprint spoofing via Camoufox (canvas, WebGL, audio, screen metrics, fonts)
|
|
@@ -73,14 +93,17 @@ automatically falls back to scraping github.com release pages.
|
|
|
73
93
|
npx skills add Bin-Huang/camoufox-cli
|
|
74
94
|
```
|
|
75
95
|
|
|
76
|
-
|
|
96
|
+
The skill is a short entry file. It tells the agent to run `camoufox-cli skill`,
|
|
97
|
+
which prints the usage guide that ships with the installed CLI. The agent always
|
|
98
|
+
reads the guide for the CLI version on the machine, so you do not need to
|
|
99
|
+
reinstall the skill after you upgrade camoufox-cli. If you installed the skill
|
|
100
|
+
before `camoufox-cli skill` existed, update it once (`npx skills update`, or run
|
|
101
|
+
`npx skills add` again) to get the short entry file.
|
|
77
102
|
|
|
78
103
|
```bash
|
|
79
|
-
camoufox-cli
|
|
80
|
-
camoufox-cli
|
|
81
|
-
|
|
82
|
-
camoufox-cli click @e1 # Click by ref
|
|
83
|
-
camoufox-cli close # Done
|
|
104
|
+
camoufox-cli skill # Usage guide for this version
|
|
105
|
+
camoufox-cli skill commands # Full command reference
|
|
106
|
+
camoufox-cli skill snapshot-refs # How snapshots and refs work
|
|
84
107
|
```
|
|
85
108
|
|
|
86
109
|
## Commands
|
|
@@ -218,7 +241,7 @@ Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cl
|
|
|
218
241
|
},
|
|
219
242
|
"sessions": {
|
|
220
243
|
"<your-session-name>": {
|
|
221
|
-
"proxy": "
|
|
244
|
+
"proxy": "http://user:pass@proxy.example.com:8080",
|
|
222
245
|
"locale": "zh-CN"
|
|
223
246
|
}
|
|
224
247
|
}
|
|
@@ -272,7 +295,7 @@ camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob open https:
|
|
|
272
295
|
## Architecture
|
|
273
296
|
|
|
274
297
|
```
|
|
275
|
-
CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python) ──Playwright──▶ Camoufox (Firefox)
|
|
298
|
+
CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python / Node) ──Playwright──▶ Camoufox (Firefox)
|
|
276
299
|
```
|
|
277
300
|
|
|
278
301
|
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.
|
|
@@ -1,7 +1,27 @@
|
|
|
1
1
|
# camoufox-cli
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/camoufox-cli)
|
|
4
|
+
[](https://pypi.org/project/camoufox-cli/)
|
|
5
|
+
[](https://www.npmjs.com/package/camoufox-cli)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
3
8
|
Anti-detect browser CLI & Skills for AI agents, powered by [Camoufox](https://github.com/daijro/camoufox).
|
|
4
9
|
|
|
10
|
+
Playwright and Puppeteer leak that they're automated — headless flags, canvas and
|
|
11
|
+
WebGL fingerprints, missing fonts, mismatched screen metrics. Camoufox patches those
|
|
12
|
+
at the C++ level, so the browser itself looks like a normal Firefox install.
|
|
13
|
+
|
|
14
|
+
That's the fingerprint layer only. Detection that keys on IP reputation, request rate,
|
|
15
|
+
or behavior still applies — pair it with `--proxy` and sane pacing.
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
camoufox-cli open https://example.com # Launch browser & navigate
|
|
19
|
+
camoufox-cli snapshot -i # Interactive elements only
|
|
20
|
+
# - link "More information..." [ref=e1]
|
|
21
|
+
camoufox-cli click @e1 # Click by ref
|
|
22
|
+
camoufox-cli close # Done
|
|
23
|
+
```
|
|
24
|
+
|
|
5
25
|
### Highlights
|
|
6
26
|
|
|
7
27
|
- C++-level fingerprint spoofing via Camoufox (canvas, WebGL, audio, screen metrics, fonts)
|
|
@@ -51,14 +71,17 @@ automatically falls back to scraping github.com release pages.
|
|
|
51
71
|
npx skills add Bin-Huang/camoufox-cli
|
|
52
72
|
```
|
|
53
73
|
|
|
54
|
-
|
|
74
|
+
The skill is a short entry file. It tells the agent to run `camoufox-cli skill`,
|
|
75
|
+
which prints the usage guide that ships with the installed CLI. The agent always
|
|
76
|
+
reads the guide for the CLI version on the machine, so you do not need to
|
|
77
|
+
reinstall the skill after you upgrade camoufox-cli. If you installed the skill
|
|
78
|
+
before `camoufox-cli skill` existed, update it once (`npx skills update`, or run
|
|
79
|
+
`npx skills add` again) to get the short entry file.
|
|
55
80
|
|
|
56
81
|
```bash
|
|
57
|
-
camoufox-cli
|
|
58
|
-
camoufox-cli
|
|
59
|
-
|
|
60
|
-
camoufox-cli click @e1 # Click by ref
|
|
61
|
-
camoufox-cli close # Done
|
|
82
|
+
camoufox-cli skill # Usage guide for this version
|
|
83
|
+
camoufox-cli skill commands # Full command reference
|
|
84
|
+
camoufox-cli skill snapshot-refs # How snapshots and refs work
|
|
62
85
|
```
|
|
63
86
|
|
|
64
87
|
## Commands
|
|
@@ -196,7 +219,7 @@ Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cl
|
|
|
196
219
|
},
|
|
197
220
|
"sessions": {
|
|
198
221
|
"<your-session-name>": {
|
|
199
|
-
"proxy": "
|
|
222
|
+
"proxy": "http://user:pass@proxy.example.com:8080",
|
|
200
223
|
"locale": "zh-CN"
|
|
201
224
|
}
|
|
202
225
|
}
|
|
@@ -250,7 +273,7 @@ camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob open https:
|
|
|
250
273
|
## Architecture
|
|
251
274
|
|
|
252
275
|
```
|
|
253
|
-
CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python) ──Playwright──▶ Camoufox (Firefox)
|
|
276
|
+
CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python / Node) ──Playwright──▶ Camoufox (Firefox)
|
|
254
277
|
```
|
|
255
278
|
|
|
256
279
|
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.
|
|
@@ -11,6 +11,9 @@ import tempfile
|
|
|
11
11
|
import time
|
|
12
12
|
|
|
13
13
|
from .config import load_defaults
|
|
14
|
+
from .skill import (
|
|
15
|
+
HELP_ARGS, HELP_FLAGS, SKILL_USAGE, TOPICS, render_guide, unknown_command_message, unknown_topic_message,
|
|
16
|
+
)
|
|
14
17
|
|
|
15
18
|
|
|
16
19
|
SOCKET_PREFIX = "/tmp/camoufox-cli-"
|
|
@@ -224,6 +227,11 @@ def parse_args(args: list[str]) -> tuple[dict, dict]:
|
|
|
224
227
|
|
|
225
228
|
def build_command(action: str, rest: list[str]) -> dict:
|
|
226
229
|
"""Build JSON command from action and remaining args."""
|
|
230
|
+
# Agents often try `--help` or `<command> --help` to learn the CLI. Only the
|
|
231
|
+
# first argument counts: `fill @e1 --help` must still type the text "--help".
|
|
232
|
+
if action in HELP_ARGS or (len(rest) > 1 and rest[1] in HELP_FLAGS):
|
|
233
|
+
print(USAGE)
|
|
234
|
+
sys.exit(0)
|
|
227
235
|
match action:
|
|
228
236
|
# Navigation
|
|
229
237
|
case "open":
|
|
@@ -352,8 +360,19 @@ def build_command(action: str, rest: list[str]) -> dict:
|
|
|
352
360
|
else:
|
|
353
361
|
return {"id": "r1", "action": "cookies", "params": {"op": "list"}}
|
|
354
362
|
|
|
363
|
+
# Usage guide
|
|
364
|
+
case "skill":
|
|
365
|
+
topic = rest[1] if len(rest) > 1 else "usage"
|
|
366
|
+
if len(rest) > 2:
|
|
367
|
+
print(SKILL_USAGE, file=sys.stderr)
|
|
368
|
+
sys.exit(1)
|
|
369
|
+
if topic not in TOPICS:
|
|
370
|
+
print(unknown_topic_message(topic), file=sys.stderr)
|
|
371
|
+
sys.exit(1)
|
|
372
|
+
return {"id": "r1", "action": "skill", "params": {"topic": topic}}
|
|
373
|
+
|
|
355
374
|
case _:
|
|
356
|
-
print(f"
|
|
375
|
+
print(f"{unknown_command_message(action, get_version())}\n\n{USAGE}", file=sys.stderr)
|
|
357
376
|
sys.exit(1)
|
|
358
377
|
|
|
359
378
|
|
|
@@ -517,6 +536,11 @@ def main():
|
|
|
517
536
|
_install_system_deps()
|
|
518
537
|
return
|
|
519
538
|
|
|
539
|
+
# Client-side: skill
|
|
540
|
+
if action == "skill":
|
|
541
|
+
sys.stdout.write(render_guide(command["params"]["topic"], get_version()))
|
|
542
|
+
return
|
|
543
|
+
|
|
520
544
|
# Client-side: sessions
|
|
521
545
|
if action == "sessions":
|
|
522
546
|
sessions = list_sessions()
|
|
@@ -627,6 +651,9 @@ Session:
|
|
|
627
651
|
|
|
628
652
|
Setup:
|
|
629
653
|
install [--with-deps] Download browser (--with-deps: system libs)
|
|
654
|
+
skill [topic] Print the usage guide for this version
|
|
655
|
+
(topics: commands, snapshot-refs)
|
|
656
|
+
help, --help Print this usage text
|
|
630
657
|
|
|
631
658
|
Flags:
|
|
632
659
|
--session <name> Session name (default: "default")
|
|
@@ -636,7 +663,7 @@ Flags:
|
|
|
636
663
|
--headed Show browser window
|
|
637
664
|
--timeout <secs> Daemon idle timeout (default: 1800)
|
|
638
665
|
--json Output as JSON
|
|
639
|
-
--persistent [path]
|
|
666
|
+
--persistent [path] Persistent identity — freeze fingerprint/OS/locale + store cookies/state (default: ~/.camoufox-cli/profiles/<session>)
|
|
640
667
|
--proxy <url> Proxy server (e.g. http://host:port or https://host:443)
|
|
641
668
|
--no-geoip Disable automatic GeoIP spoofing (auto-enabled with --proxy)
|
|
642
669
|
--locale <tag> Force browser locale (e.g. "en-US" or "en-US,zh-CN")
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Command Reference
|
|
2
|
+
|
|
3
|
+
Complete reference for all camoufox-cli commands. For quick start and common patterns, run `camoufox-cli skill`.
|
|
4
|
+
|
|
5
|
+
## Navigation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
camoufox-cli open <url> # Navigate to URL (starts daemon if needed)
|
|
9
|
+
# Auto-prepends https:// if no protocol given
|
|
10
|
+
camoufox-cli back # Go back
|
|
11
|
+
camoufox-cli forward # Go forward
|
|
12
|
+
camoufox-cli reload # Reload page
|
|
13
|
+
camoufox-cli url # Print current URL
|
|
14
|
+
camoufox-cli title # Print page title
|
|
15
|
+
camoufox-cli close # Close your tab (browser exits when the last tab closes)
|
|
16
|
+
camoufox-cli close --all # Force-close every session on this machine, other agents' too (only when the user asks)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Snapshot (Page Analysis)
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
camoufox-cli snapshot # Full accessibility tree
|
|
23
|
+
camoufox-cli snapshot -i # Interactive elements only (recommended)
|
|
24
|
+
camoufox-cli snapshot -s "#main" # Scope to CSS selector
|
|
25
|
+
camoufox-cli snapshot -i -s "form" # Interactive + scoped
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Interactions (use @refs from snapshot)
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
camoufox-cli click @e1 # Click element
|
|
32
|
+
camoufox-cli fill @e1 "text" # Clear and type
|
|
33
|
+
camoufox-cli type @e1 "text" # Type without clearing (append)
|
|
34
|
+
camoufox-cli select @e1 "value" # Select dropdown option
|
|
35
|
+
camoufox-cli check @e1 # Toggle checkbox
|
|
36
|
+
camoufox-cli hover @e1 # Hover over element
|
|
37
|
+
camoufox-cli mouse click 660 380 # Click at viewport coordinates (no ref needed)
|
|
38
|
+
camoufox-cli press Enter # Press key
|
|
39
|
+
camoufox-cli press "Control+a" # Key combination
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Get Information
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
camoufox-cli text @e1 # Get element text (by ref)
|
|
46
|
+
camoufox-cli text body # Get all page text (by CSS selector)
|
|
47
|
+
camoufox-cli url # Get current URL
|
|
48
|
+
camoufox-cli title # Get page title
|
|
49
|
+
camoufox-cli eval "document.title" # Run JavaScript expression
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Screenshots and PDF
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
camoufox-cli screenshot # Screenshot to stdout (base64)
|
|
56
|
+
camoufox-cli screenshot page.png # Save to file
|
|
57
|
+
camoufox-cli screenshot --full p.png # Full page screenshot
|
|
58
|
+
camoufox-cli pdf output.pdf # Save page as PDF
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Scroll
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
camoufox-cli scroll down # Scroll down 500px (default)
|
|
65
|
+
camoufox-cli scroll up # Scroll up 500px
|
|
66
|
+
camoufox-cli scroll down 1000 # Scroll down 1000px
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Wait
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
camoufox-cli wait @e1 # Wait for element to appear
|
|
73
|
+
camoufox-cli wait 2000 # Wait milliseconds
|
|
74
|
+
camoufox-cli wait --url "*/dashboard" # Wait for URL pattern
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Tabs
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
camoufox-cli tabs # List open tabs (with owner names)
|
|
81
|
+
camoufox-cli switch 2 # Switch to tab by index
|
|
82
|
+
camoufox-cli --tab <name> <cmd> # Named tab: shared browser + cookies/login,
|
|
83
|
+
# independent page/refs/history per tab
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Named tabs are the cheap way to run concurrent agents as one identity: every tab shares the session's single browser (same fingerprint, same login state), while snapshot refs and history stay per-tab. A finishing agent runs `close` addressed to its own tab (`--tab <name> close`) — that releases only this tab, and the browser exits by itself when the last tab closes, so no coordination between agents is needed. Tab names must be unique per agent: generate one once — a task slug + shell-generated random suffix, e.g. `TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB"` — and reuse the printed name for every command; don't invent the suffix yourself (LLM-"random" characters collide). If you lose the name, `camoufox-cli tabs` lists every tab with its owner name. Never use `close --all` to clean up: it closes every agent's browser.
|
|
87
|
+
|
|
88
|
+
## Cookies
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
camoufox-cli cookies # Dump cookies as JSON
|
|
92
|
+
camoufox-cli cookies import file.json # Import cookies from file
|
|
93
|
+
camoufox-cli cookies export file.json # Export cookies to file
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Sessions
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
camoufox-cli sessions # List active sessions
|
|
100
|
+
camoufox-cli --session <name> <cmd> # Run command in named session
|
|
101
|
+
camoufox-cli close --all # Force-close every session on this machine, other agents' too (only when the user asks)
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
A session is a separate browser instance with its own fingerprint, cookies, and launch options (proxy/locale/persistent). For concurrent agents acting as ONE identity, prefer named tabs (see Tabs above) — one browser instead of N.
|
|
105
|
+
|
|
106
|
+
## JavaScript
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
camoufox-cli eval "document.title" # Simple expression
|
|
110
|
+
camoufox-cli eval "document.querySelectorAll('img').length"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
For complex JavaScript with nested quotes, wrap the expression in single quotes and use double quotes inside it.
|
|
114
|
+
|
|
115
|
+
## Setup
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
camoufox-cli install # Download Camoufox browser
|
|
119
|
+
camoufox-cli install --with-deps # Download browser + system libs (Linux)
|
|
120
|
+
camoufox-cli skill [topic] # Print the usage guide for this version (topics: commands, snapshot-refs)
|
|
121
|
+
camoufox-cli --help # Print the usage text
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Global Options
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
camoufox-cli --session <name> ... # Separate browser instance (own fingerprint/cookies/proxy)
|
|
128
|
+
camoufox-cli --tab <name> ... # Named tab in the session's shared browser
|
|
129
|
+
camoufox-cli --headed ... # Show browser window (not headless)
|
|
130
|
+
camoufox-cli --json ... # JSON output for parsing
|
|
131
|
+
camoufox-cli --timeout <seconds> ... # Daemon idle timeout (default: 1800)
|
|
132
|
+
camoufox-cli --persistent [path] ... # Persistent identity — reuse the same fingerprint + cookies
|
|
133
|
+
# across launches (default: ~/.camoufox-cli/profiles/<session>)
|
|
134
|
+
camoufox-cli --proxy <url> ... # Proxy server (e.g. http://host:port or http://user:pass@host:port)
|
|
135
|
+
camoufox-cli --no-geoip ... # Disable automatic GeoIP spoofing (auto-enabled with --proxy)
|
|
136
|
+
camoufox-cli --locale <tag> ... # Force browser locale (e.g. "en-US" or "en-US,zh-CN")
|
|
137
|
+
camoufox-cli --version # Print version and exit
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### `--persistent` in detail
|
|
141
|
+
|
|
142
|
+
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. `camoufox-cli skill` has a longer section on persistent identity.
|
|
143
|
+
|
|
144
|
+
### Config file
|
|
145
|
+
|
|
146
|
+
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.
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"default": { "persistent": true, "timeout": 3600 },
|
|
151
|
+
"sessions": { "<your-session-name>": { "proxy": "http://user:pass@proxy.example.com:8080", "locale": "zh-CN" } }
|
|
152
|
+
}
|
|
153
|
+
```
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Snapshot and Refs
|
|
2
|
+
|
|
3
|
+
Compact element references for AI agents to interact with page elements efficiently.
|
|
4
|
+
|
|
5
|
+
**Related**: `camoufox-cli skill commands` for the full command reference, `camoufox-cli skill` for quick start.
|
|
6
|
+
|
|
7
|
+
## Contents
|
|
8
|
+
|
|
9
|
+
- [How Refs Work](#how-refs-work)
|
|
10
|
+
- [Snapshot Command](#the-snapshot-command)
|
|
11
|
+
- [Using Refs](#using-refs)
|
|
12
|
+
- [Ref Lifecycle](#ref-lifecycle)
|
|
13
|
+
- [Best Practices](#best-practices)
|
|
14
|
+
- [Troubleshooting](#troubleshooting)
|
|
15
|
+
|
|
16
|
+
## How Refs Work
|
|
17
|
+
|
|
18
|
+
Traditional approach:
|
|
19
|
+
```
|
|
20
|
+
Full DOM/HTML -> AI parses -> CSS selector -> Action (~3000-5000 tokens)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
camoufox-cli approach:
|
|
24
|
+
```
|
|
25
|
+
Compact aria snapshot -> @refs assigned -> Direct interaction (~200-400 tokens)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
## The Snapshot Command
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Basic snapshot (shows full page structure)
|
|
34
|
+
camoufox-cli snapshot
|
|
35
|
+
|
|
36
|
+
# Interactive snapshot (-i flag) - RECOMMENDED
|
|
37
|
+
camoufox-cli snapshot -i
|
|
38
|
+
|
|
39
|
+
# Scoped to a specific container
|
|
40
|
+
camoufox-cli snapshot -s "#main-content"
|
|
41
|
+
camoufox-cli snapshot -i -s "form.login"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Snapshot Output Format
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
- heading "Example Domain" [ref=e1]
|
|
48
|
+
- navigation
|
|
49
|
+
- link "Home" [ref=e2]
|
|
50
|
+
- link "Products" [ref=e3]
|
|
51
|
+
- link "About" [ref=e4]
|
|
52
|
+
- button "Sign In" [ref=e5]
|
|
53
|
+
- main
|
|
54
|
+
- heading "Welcome" [ref=e6]
|
|
55
|
+
- textbox "Email" [ref=e7]
|
|
56
|
+
- textbox "Password" [ref=e8]
|
|
57
|
+
- button "Log In" [ref=e9]
|
|
58
|
+
- contentinfo
|
|
59
|
+
- link "Privacy Policy" [ref=e10]
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
With `-i` (interactive only), non-interactive elements are filtered out:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
- link "Home" [ref=e1]
|
|
66
|
+
- link "Products" [ref=e2]
|
|
67
|
+
- link "About" [ref=e3]
|
|
68
|
+
- button "Sign In" [ref=e4]
|
|
69
|
+
- textbox "Email" [ref=e5]
|
|
70
|
+
- textbox "Password" [ref=e6]
|
|
71
|
+
- button "Log In" [ref=e7]
|
|
72
|
+
- link "Privacy Policy" [ref=e8]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Using Refs
|
|
76
|
+
|
|
77
|
+
Once you have refs, interact directly:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
# Click the "Sign In" button
|
|
81
|
+
camoufox-cli click @e4
|
|
82
|
+
|
|
83
|
+
# Fill email input
|
|
84
|
+
camoufox-cli fill @e5 "user@example.com"
|
|
85
|
+
|
|
86
|
+
# Fill password
|
|
87
|
+
camoufox-cli fill @e6 "password123"
|
|
88
|
+
|
|
89
|
+
# Submit the form
|
|
90
|
+
camoufox-cli click @e7
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Ref Lifecycle
|
|
94
|
+
|
|
95
|
+
**IMPORTANT**: Refs are invalidated when the page changes!
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# Get initial snapshot
|
|
101
|
+
camoufox-cli snapshot -i
|
|
102
|
+
# - button "Next" [ref=e1]
|
|
103
|
+
|
|
104
|
+
# Click triggers page change
|
|
105
|
+
camoufox-cli click @e1
|
|
106
|
+
|
|
107
|
+
# MUST re-snapshot to get new refs!
|
|
108
|
+
camoufox-cli snapshot -i
|
|
109
|
+
# - heading "Page 2" [ref=e1] <- Different element now!
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### What Invalidates Refs
|
|
113
|
+
|
|
114
|
+
- **Navigation**: clicking links, form submissions, redirects
|
|
115
|
+
- **Dynamic content**: dropdowns opening, modals appearing, AJAX updates
|
|
116
|
+
- **Scrolling**: if it triggers lazy loading of new content
|
|
117
|
+
- **JavaScript**: any DOM mutation that changes element order
|
|
118
|
+
|
|
119
|
+
### What Happens with Stale Refs
|
|
120
|
+
|
|
121
|
+
When you use a ref without re-snapshotting after a page change:
|
|
122
|
+
- The ref may point to a **different element** (wrong click target)
|
|
123
|
+
- The ref may **not exist** (error)
|
|
124
|
+
- The action may **silently succeed on the wrong element**
|
|
125
|
+
|
|
126
|
+
This is the most common source of automation errors. When in doubt, re-snapshot.
|
|
127
|
+
|
|
128
|
+
## Best Practices
|
|
129
|
+
|
|
130
|
+
### 1. Always Snapshot Before Interacting
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# CORRECT
|
|
134
|
+
camoufox-cli open https://example.com
|
|
135
|
+
camoufox-cli snapshot -i # Get refs first
|
|
136
|
+
camoufox-cli click @e1 # Use ref
|
|
137
|
+
|
|
138
|
+
# WRONG
|
|
139
|
+
camoufox-cli open https://example.com
|
|
140
|
+
camoufox-cli click @e1 # Ref doesn't exist yet!
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 2. Re-Snapshot After Navigation
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
camoufox-cli click @e5 # Navigates to new page
|
|
147
|
+
camoufox-cli snapshot -i # Get new refs
|
|
148
|
+
camoufox-cli click @e1 # Use new refs
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 3. Re-Snapshot After Dynamic Changes
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
camoufox-cli click @e1 # Opens dropdown
|
|
155
|
+
camoufox-cli snapshot -i # See dropdown items
|
|
156
|
+
camoufox-cli click @e7 # Select item
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 4. Scope Snapshots on Complex Pages
|
|
160
|
+
|
|
161
|
+
For pages with many elements, scope the snapshot to reduce noise:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
camoufox-cli snapshot -i -s "#login-form"
|
|
165
|
+
camoufox-cli snapshot -i -s ".product-list"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### 5. Wait Before Snapshot on Slow Pages
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
camoufox-cli open https://slow-site.com
|
|
172
|
+
camoufox-cli wait 3000 # Wait for content to load
|
|
173
|
+
camoufox-cli snapshot -i # Now snapshot
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Troubleshooting
|
|
177
|
+
|
|
178
|
+
### "Ref @eN not found"
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
# Ref was invalidated - re-snapshot
|
|
182
|
+
camoufox-cli snapshot -i
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Common causes:
|
|
186
|
+
- Page navigated since last snapshot
|
|
187
|
+
- Dynamic content changed the DOM
|
|
188
|
+
- Never took a snapshot after opening the page
|
|
189
|
+
|
|
190
|
+
### Element Not Visible in Snapshot
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
# Scroll down to reveal element
|
|
194
|
+
camoufox-cli scroll down 1000
|
|
195
|
+
camoufox-cli snapshot -i
|
|
196
|
+
|
|
197
|
+
# Or wait for dynamic content
|
|
198
|
+
camoufox-cli wait 2000
|
|
199
|
+
camoufox-cli snapshot -i
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Too Many Elements
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
# Scope to specific container
|
|
206
|
+
camoufox-cli snapshot -i -s "#main"
|
|
207
|
+
|
|
208
|
+
# Or use text extraction for content-only
|
|
209
|
+
camoufox-cli text body
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Duplicate Elements (Same Role + Name)
|
|
213
|
+
|
|
214
|
+
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:
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
- button "Submit" [ref=e3]
|
|
218
|
+
- button "Submit" [ref=e7] [nth=1]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Both refs work independently. Use the one that corresponds to the element you need.
|
|
@@ -0,0 +1,402 @@
|
|
|
1
|
+
# Anti-Detect Browser Automation with camoufox-cli
|
|
2
|
+
|
|
3
|
+
## Core Workflow
|
|
4
|
+
|
|
5
|
+
Every browser automation follows this pattern:
|
|
6
|
+
|
|
7
|
+
1. **Navigate**: `camoufox-cli open <url>`
|
|
8
|
+
2. **Snapshot**: `camoufox-cli snapshot -i` (get element refs like `@e1`, `@e2`)
|
|
9
|
+
3. **Interact**: Use refs to click, fill, select
|
|
10
|
+
4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
|
|
11
|
+
5. **Close**: `camoufox-cli close` when the entire task is complete — with the same `--tab`/`--session` flags as your other commands. Keep it open if the user may have follow-up instructions.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
camoufox-cli open https://example.com/form
|
|
15
|
+
camoufox-cli snapshot -i
|
|
16
|
+
# Output: - textbox "Email" [ref=e1]
|
|
17
|
+
# - textbox "Password" [ref=e2]
|
|
18
|
+
# - button "Submit" [ref=e3]
|
|
19
|
+
|
|
20
|
+
camoufox-cli fill @e1 "user@example.com"
|
|
21
|
+
camoufox-cli fill @e2 "password123"
|
|
22
|
+
camoufox-cli click @e3
|
|
23
|
+
camoufox-cli snapshot -i # Check result
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Command Chaining
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Chain open + snapshot in one call
|
|
32
|
+
camoufox-cli open https://example.com && camoufox-cli snapshot -i
|
|
33
|
+
|
|
34
|
+
# Chain multiple interactions
|
|
35
|
+
camoufox-cli fill @e1 "user@example.com" && camoufox-cli fill @e2 "password123" && camoufox-cli click @e3
|
|
36
|
+
|
|
37
|
+
# Navigate and capture
|
|
38
|
+
camoufox-cli open https://example.com && camoufox-cli screenshot page.png
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**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).
|
|
42
|
+
|
|
43
|
+
## Essential Commands
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# Navigation
|
|
47
|
+
camoufox-cli open <url> # Navigate to URL (starts daemon if needed)
|
|
48
|
+
camoufox-cli back # Go back
|
|
49
|
+
camoufox-cli forward # Go forward
|
|
50
|
+
camoufox-cli reload # Reload page
|
|
51
|
+
camoufox-cli url # Print current URL
|
|
52
|
+
camoufox-cli title # Print page title
|
|
53
|
+
camoufox-cli close # Close your tab (browser exits when the last tab closes)
|
|
54
|
+
|
|
55
|
+
# Snapshot
|
|
56
|
+
camoufox-cli snapshot # Full aria tree of page
|
|
57
|
+
camoufox-cli snapshot -i # Interactive elements only (recommended)
|
|
58
|
+
camoufox-cli snapshot -s "#selector" # Scope to CSS selector
|
|
59
|
+
|
|
60
|
+
# Interaction (use @refs from snapshot)
|
|
61
|
+
camoufox-cli click @e1 # Click element
|
|
62
|
+
camoufox-cli fill @e1 "text" # Clear + type into input
|
|
63
|
+
camoufox-cli type @e1 "text" # Type without clearing (append)
|
|
64
|
+
camoufox-cli select @e1 "option" # Select dropdown option
|
|
65
|
+
camoufox-cli check @e1 # Toggle checkbox
|
|
66
|
+
camoufox-cli hover @e1 # Hover over element
|
|
67
|
+
camoufox-cli mouse click 660 380 # Click at viewport coordinates (no ref needed)
|
|
68
|
+
camoufox-cli press Enter # Press keyboard key
|
|
69
|
+
camoufox-cli press "Control+a" # Key combination
|
|
70
|
+
|
|
71
|
+
# Data Extraction
|
|
72
|
+
camoufox-cli text @e1 # Get text content of element
|
|
73
|
+
camoufox-cli text body # Get all page text (CSS selector)
|
|
74
|
+
camoufox-cli eval "document.title" # Execute JavaScript
|
|
75
|
+
|
|
76
|
+
# Capture
|
|
77
|
+
camoufox-cli screenshot # Screenshot as JSON {"base64": "..."}
|
|
78
|
+
camoufox-cli screenshot page.png # Screenshot to file
|
|
79
|
+
camoufox-cli screenshot --full p.png # Full page screenshot
|
|
80
|
+
camoufox-cli pdf output.pdf # Save page as PDF
|
|
81
|
+
|
|
82
|
+
# Scroll & Wait
|
|
83
|
+
camoufox-cli scroll down # Scroll down 500px
|
|
84
|
+
camoufox-cli scroll up # Scroll up 500px
|
|
85
|
+
camoufox-cli scroll down 1000 # Scroll down 1000px
|
|
86
|
+
camoufox-cli wait @e1 # Wait for element to appear
|
|
87
|
+
camoufox-cli wait 2000 # Wait milliseconds
|
|
88
|
+
camoufox-cli wait --url "*/dashboard" # Wait for URL pattern
|
|
89
|
+
|
|
90
|
+
# Tabs
|
|
91
|
+
camoufox-cli tabs # List open tabs (with owner names)
|
|
92
|
+
camoufox-cli switch 2 # Switch to tab by index
|
|
93
|
+
camoufox-cli --tab <unique-name> open <url> # Named tab: shared browser + login, own page/refs
|
|
94
|
+
|
|
95
|
+
# Cookies & State
|
|
96
|
+
camoufox-cli cookies # Dump cookies as JSON
|
|
97
|
+
camoufox-cli cookies import file.json # Import cookies
|
|
98
|
+
camoufox-cli cookies export file.json # Export cookies
|
|
99
|
+
|
|
100
|
+
# Sessions
|
|
101
|
+
camoufox-cli sessions # List active sessions
|
|
102
|
+
camoufox-cli --session work open <url> # Use named session
|
|
103
|
+
camoufox-cli close --all # Force-close every session on this machine, other agents' too (only when the user asks)
|
|
104
|
+
|
|
105
|
+
# Setup
|
|
106
|
+
camoufox-cli install # Download Camoufox browser
|
|
107
|
+
camoufox-cli install --with-deps # Download browser + system libs (Linux)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Common Patterns
|
|
111
|
+
|
|
112
|
+
### Form Submission
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
camoufox-cli open https://example.com/signup
|
|
116
|
+
camoufox-cli snapshot -i
|
|
117
|
+
camoufox-cli fill @e1 "Jane Doe"
|
|
118
|
+
camoufox-cli fill @e2 "jane@example.com"
|
|
119
|
+
camoufox-cli select @e3 "California"
|
|
120
|
+
camoufox-cli check @e4
|
|
121
|
+
camoufox-cli click @e5
|
|
122
|
+
camoufox-cli snapshot -i # Verify submission result
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Data Extraction
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
camoufox-cli open https://example.com/products
|
|
129
|
+
camoufox-cli snapshot -i
|
|
130
|
+
camoufox-cli text @e5 # Get specific element text
|
|
131
|
+
camoufox-cli eval "document.title" # Get page title via JS
|
|
132
|
+
camoufox-cli screenshot results.png # Visual capture
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Cookie Management (Persist Login)
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# Login and export cookies
|
|
139
|
+
camoufox-cli open https://app.example.com/login
|
|
140
|
+
camoufox-cli snapshot -i
|
|
141
|
+
camoufox-cli fill @e1 "user"
|
|
142
|
+
camoufox-cli fill @e2 "pass"
|
|
143
|
+
camoufox-cli click @e3
|
|
144
|
+
camoufox-cli cookies export auth.json
|
|
145
|
+
|
|
146
|
+
# Restore in future session
|
|
147
|
+
camoufox-cli open https://app.example.com
|
|
148
|
+
camoufox-cli cookies import auth.json
|
|
149
|
+
camoufox-cli reload
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
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.
|
|
153
|
+
|
|
154
|
+
### Multiple Tabs
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
camoufox-cli open https://site-a.com
|
|
158
|
+
camoufox-cli eval "window.open('https://site-b.com')"
|
|
159
|
+
camoufox-cli tabs # List tabs
|
|
160
|
+
camoufox-cli switch 1 # Switch to second tab
|
|
161
|
+
camoufox-cli snapshot -i
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Parallel Tabs (shared identity, one browser)
|
|
165
|
+
|
|
166
|
+
Named tabs share one browser within a session — same fingerprint, same cookies/login state — but each tab keeps its own page, element refs, and navigation history, so concurrent agents never clobber each other. This is the cheap way to parallelize: one Firefox total, roughly 50-150MB per extra tab.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
camoufox-cli --tab inbox-scan-x4q open https://app.example.com/inbox
|
|
170
|
+
camoufox-cli --tab report-pull-9kf open https://app.example.com/reports
|
|
171
|
+
camoufox-cli --tab inbox-scan-x4q snapshot -i # refs are per tab
|
|
172
|
+
camoufox-cli tabs # Lists every tab with its owner name
|
|
173
|
+
camoufox-cli --tab inbox-scan-x4q close # Frees only this tab; browser stays for the others
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Picking your tab name.** Nothing enforces uniqueness — two agents using the same name share one page pointer and will clobber each other. Generate your name ONCE at the start of your task: a short slug of *your specific task* plus a shell-generated random suffix — don't invent the suffix yourself, LLM-"random" characters are biased and concurrent agents may produce the same ones. Then reuse the printed name verbatim in every subsequent command. (If your instructions explicitly assign you a tab name, use that instead.)
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB" && camoufox-cli --tab "$TAB" open https://example.com
|
|
180
|
+
# prints e.g. price-scan-9f3c — use that exact name in every later command:
|
|
181
|
+
camoufox-cli --tab price-scan-9f3c snapshot -i
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
If you lose your tab name, run `camoufox-cli tabs`: it lists every tab with its owner name. Never use `close --all` to clean up: it closes the browsers of every agent and user on this machine.
|
|
185
|
+
|
|
186
|
+
Use tabs when subagents should act as the same identity (e.g. all operating the same logged-in account). Cleanup needs no coordination: every agent runs `close` when done, addressed to its own tab (`camoufox-cli --tab <name> close`) — it releases only that tab, and the browser exits by itself when the last tab closes.
|
|
187
|
+
|
|
188
|
+
Tabs share one browser process, so commands from different tabs may queue behind a slow navigation or `wait`; separate sessions run as independent processes and execute fully in parallel. If a few agents are extremely command-heavy, consider giving those their own session and keeping the rest on tabs.
|
|
189
|
+
|
|
190
|
+
### Parallel Sessions (isolated identities)
|
|
191
|
+
|
|
192
|
+
Each named session is a separate browser process, so each gets its own randomly-generated fingerprint and its own cookies. Use this when agents must NOT share identity (multi-account work) — it costs a full Firefox (~300-500MB) per session:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
camoufox-cli --session s1 open https://site-a.com
|
|
196
|
+
camoufox-cli --session s2 open https://site-b.com
|
|
197
|
+
camoufox-cli sessions # List both
|
|
198
|
+
camoufox-cli --session s1 snapshot -i
|
|
199
|
+
camoufox-cli --session s2 snapshot -i
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Separate sessions alone only isolate the browser side. For multi-account work that must survive scrutiny, also give each session its own proxy (sites correlate accounts by IP — use the config file's `sessions.<name>.proxy`) and `--persistent` (otherwise the fingerprint is re-randomized every launch, which looks like a new device on each login).
|
|
203
|
+
|
|
204
|
+
### Visual Browser (Debugging)
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
camoufox-cli --headed open https://example.com
|
|
208
|
+
camoufox-cli snapshot -i
|
|
209
|
+
camoufox-cli screenshot debug.png
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Session Management and Cleanup
|
|
213
|
+
|
|
214
|
+
When running multiple agents or automations concurrently, give each agent its own name so they don't conflict. Two isolation levels:
|
|
215
|
+
|
|
216
|
+
- **`--tab <name>`** (shared identity, recommended default): all agents share one browser — same fingerprint and login state — but each gets an independent tab. Cheap: one Firefox total.
|
|
217
|
+
- **`--session <name>`** (isolated identity): each agent gets its own browser with its own fingerprint and cookies. Expensive: a full Firefox per session. Use only when identities must be separate.
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
# Shared identity: 3 agents, one browser, one login
|
|
221
|
+
camoufox-cli --tab orders-audit-p2m open https://app.example.com/a
|
|
222
|
+
camoufox-cli --tab user-export-j8w open https://app.example.com/b
|
|
223
|
+
camoufox-cli --tab billing-check-r4t open https://app.example.com/c
|
|
224
|
+
|
|
225
|
+
# Isolated identities: 2 agents, two browsers
|
|
226
|
+
camoufox-cli --session shop-a-buyer open https://site-a.com
|
|
227
|
+
camoufox-cli --session shop-b-buyer open https://site-b.com
|
|
228
|
+
camoufox-cli sessions # Check active sessions
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Names are just strings and nothing enforces uniqueness — follow the "Picking your tab name" rule above (task slug + shell-generated random suffix, chosen once). The same applies to session names.
|
|
232
|
+
|
|
233
|
+
When the task is done (see Core Workflow above), run `close` to avoid leaked processes — with the same `--tab`/`--session` flags as your other commands, since `close` releases the tab the command is addressed to. The browser exits when the last tab closes, so every agent cleans up the same way without knowing about the others:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
camoufox-cli --tab orders-audit-p2m close # Free this tab; browser exits if it was the last
|
|
237
|
+
camoufox-cli close # Same, for the default tab
|
|
238
|
+
camoufox-cli --session shop-a-buyer close # Same, within a named session
|
|
239
|
+
camoufox-cli close --all # Force-close every session on this machine (only when the user asks)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
If a previous session was not closed properly, the daemon may still be running. Run `camoufox-cli close` with that session's `--session`/`--tab` flags to clean it up. Do not use `close --all` for this: other agents may still use their sessions.
|
|
243
|
+
|
|
244
|
+
## Timeouts and Slow Pages
|
|
245
|
+
|
|
246
|
+
Some pages take time to fully load, especially those with dynamic content or heavy JavaScript. Use explicit waits before taking a snapshot:
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
# Wait for a specific element to appear
|
|
250
|
+
camoufox-cli wait @e1
|
|
251
|
+
camoufox-cli snapshot -i
|
|
252
|
+
|
|
253
|
+
# Wait for a URL pattern (useful after redirects)
|
|
254
|
+
camoufox-cli wait --url "*/dashboard"
|
|
255
|
+
camoufox-cli snapshot -i
|
|
256
|
+
|
|
257
|
+
# Wait a fixed duration as a last resort
|
|
258
|
+
camoufox-cli wait 3000
|
|
259
|
+
camoufox-cli snapshot -i
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
When dealing with slow pages, always wait before snapshotting. If you snapshot too early, elements may be missing from the output.
|
|
263
|
+
|
|
264
|
+
## Ref Lifecycle (Important)
|
|
265
|
+
|
|
266
|
+
Refs (`@e1`, `@e2`, etc.) are **temporary identifiers** assigned by sequential numbering during each snapshot. They are invalidated when the page changes.
|
|
267
|
+
|
|
268
|
+
**Always re-snapshot after:**
|
|
269
|
+
|
|
270
|
+
- Clicking links or buttons that navigate
|
|
271
|
+
- Form submissions
|
|
272
|
+
- Dynamic content loading (dropdowns, modals, lazy-loaded content)
|
|
273
|
+
- Scrolling that triggers new content
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
# CORRECT: re-snapshot after navigation
|
|
277
|
+
camoufox-cli click @e5 # Navigates to new page
|
|
278
|
+
camoufox-cli snapshot -i # MUST re-snapshot
|
|
279
|
+
camoufox-cli click @e1 # Use new refs
|
|
280
|
+
|
|
281
|
+
# CORRECT: re-snapshot after dynamic changes
|
|
282
|
+
camoufox-cli click @e1 # Opens dropdown
|
|
283
|
+
camoufox-cli snapshot -i # See dropdown items
|
|
284
|
+
camoufox-cli click @e7 # Select item
|
|
285
|
+
|
|
286
|
+
# WRONG: using refs without snapshot
|
|
287
|
+
camoufox-cli open https://example.com
|
|
288
|
+
camoufox-cli click @e1 # Ref doesn't exist yet!
|
|
289
|
+
|
|
290
|
+
# WRONG: using old refs after navigation
|
|
291
|
+
camoufox-cli click @e5 # Navigates away
|
|
292
|
+
camoufox-cli click @e3 # STALE REF - wrong element!
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Always take a fresh snapshot before interacting with elements after navigation or page changes.
|
|
296
|
+
|
|
297
|
+
## Troubleshooting
|
|
298
|
+
|
|
299
|
+
### "Ref @eN not found"
|
|
300
|
+
|
|
301
|
+
The ref was invalidated. Re-snapshot to get fresh refs:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
camoufox-cli snapshot -i
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
### Element Not Visible in Snapshot
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
# Scroll down to reveal element
|
|
311
|
+
camoufox-cli scroll down 1000
|
|
312
|
+
camoufox-cli snapshot -i
|
|
313
|
+
|
|
314
|
+
# Or wait for dynamic content
|
|
315
|
+
camoufox-cli wait 2000
|
|
316
|
+
camoufox-cli snapshot -i
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Element Visible on Screen but Not in Snapshot
|
|
320
|
+
|
|
321
|
+
A checkbox inside a cross-origin iframe (for example a Cloudflare Turnstile
|
|
322
|
+
"Verify you are human" widget) has no ref. Find it in a screenshot and click by
|
|
323
|
+
coordinates. Coordinates are viewport CSS pixels. At the default
|
|
324
|
+
`devicePixelRatio` of 1, they equal the pixels of a non-`--full` screenshot.
|
|
325
|
+
|
|
326
|
+
```bash
|
|
327
|
+
camoufox-cli screenshot page.png # Locate the checkbox in the image
|
|
328
|
+
camoufox-cli mouse click 660 380 # Click its center
|
|
329
|
+
camoufox-cli wait 3000
|
|
330
|
+
camoufox-cli screenshot page.png # Confirm the check passed
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
### Too Many Elements in Snapshot
|
|
334
|
+
|
|
335
|
+
```bash
|
|
336
|
+
# Scope to a specific container
|
|
337
|
+
camoufox-cli snapshot -s "#main-content"
|
|
338
|
+
camoufox-cli snapshot -i -s "form.login"
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
### Page Not Fully Loaded
|
|
342
|
+
|
|
343
|
+
```bash
|
|
344
|
+
# Wait for URL pattern after redirect
|
|
345
|
+
camoufox-cli wait --url "*/dashboard"
|
|
346
|
+
camoufox-cli snapshot -i
|
|
347
|
+
|
|
348
|
+
# Wait a fixed duration as last resort
|
|
349
|
+
camoufox-cli wait 3000
|
|
350
|
+
camoufox-cli snapshot -i
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
## Global Flags
|
|
354
|
+
|
|
355
|
+
```
|
|
356
|
+
--session <name> Named session (default: "default")
|
|
357
|
+
--tab <name> Named tab within the session's shared browser: same
|
|
358
|
+
fingerprint and cookies/login, independent page/refs/
|
|
359
|
+
history (default: "default")
|
|
360
|
+
--headed Show browser window (default: headless)
|
|
361
|
+
--timeout <seconds> Daemon idle timeout (default: 1800)
|
|
362
|
+
--json Output as JSON instead of human-readable
|
|
363
|
+
--persistent [path] Persistent identity — reuse the same fingerprint + cookies across launches
|
|
364
|
+
(default path: ~/.camoufox-cli/profiles/<session>)
|
|
365
|
+
--proxy <url> Proxy server (http:// or https://; auth: http://user:pass@host:port)
|
|
366
|
+
--no-geoip Disable automatic GeoIP spoofing (auto-enabled with --proxy)
|
|
367
|
+
--locale <tag> Force browser locale (e.g. "en-US" or "en-US,zh-CN")
|
|
368
|
+
--version Print version and exit
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
**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.
|
|
372
|
+
|
|
373
|
+
```json
|
|
374
|
+
{
|
|
375
|
+
"default": { "persistent": true, "timeout": 3600 },
|
|
376
|
+
"sessions": { "<your-session-name>": { "proxy": "http://user:pass@proxy.example.com:8080", "locale": "zh-CN" } }
|
|
377
|
+
}
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
## Persistent Identity
|
|
381
|
+
|
|
382
|
+
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.
|
|
383
|
+
|
|
384
|
+
**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.
|
|
385
|
+
|
|
386
|
+
```bash
|
|
387
|
+
# Parallel identities, each with its own fingerprint + cookies
|
|
388
|
+
camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
|
|
389
|
+
camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob open https://app.example.com
|
|
390
|
+
|
|
391
|
+
# Reset an identity: just remove the directory
|
|
392
|
+
rm -rf ~/.camoufox-cli/profiles/alice
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
## More Guides
|
|
396
|
+
|
|
397
|
+
This guide matches the installed camoufox-cli version. Run it again after you upgrade camoufox-cli.
|
|
398
|
+
|
|
399
|
+
```bash
|
|
400
|
+
camoufox-cli skill commands # Full command reference
|
|
401
|
+
camoufox-cli skill snapshot-refs # How snapshots and refs work, duplicate elements
|
|
402
|
+
```
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Usage guide that `camoufox-cli skill` prints.
|
|
2
|
+
|
|
3
|
+
The guide ships inside the package, so an agent always reads the guide for the
|
|
4
|
+
installed CLI version. The entry skill in skills/camoufox-cli only tells agents
|
|
5
|
+
to run `camoufox-cli skill`. Every `npm pack` copies this guide directory into
|
|
6
|
+
the JS package, which prints the same bytes.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from importlib.resources import files
|
|
10
|
+
|
|
11
|
+
TOPICS = ("usage", "commands", "snapshot-refs")
|
|
12
|
+
SKILL_USAGE = "Usage: camoufox-cli skill [commands|snapshot-refs]"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def unknown_topic_message(topic: str) -> str:
|
|
16
|
+
return f"Unknown topic: {topic}\n{SKILL_USAGE}"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
HELP_ARGS = ("help", "--help", "-h")
|
|
20
|
+
# After a command, only flags ask for help: `text help` targets a selector named "help".
|
|
21
|
+
HELP_FLAGS = ("--help", "-h")
|
|
22
|
+
|
|
23
|
+
# Commands that older guides taught. An agent with a stale skill still runs them.
|
|
24
|
+
REMOVED_COMMANDS = {
|
|
25
|
+
"close-tab": "`close` now closes only your tab; use `--tab <name> close` for a named tab",
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def render_guide(topic: str, version: str) -> str:
|
|
30
|
+
"""The guide for `topic`, between a version line and an end line.
|
|
31
|
+
|
|
32
|
+
Agents check for the end line to detect truncated command output.
|
|
33
|
+
"""
|
|
34
|
+
path = files("camoufox_cli").joinpath("guide", f"{topic}.md")
|
|
35
|
+
try:
|
|
36
|
+
body = path.read_text(encoding="utf-8")
|
|
37
|
+
except FileNotFoundError:
|
|
38
|
+
raise SystemExit(f"Error: the usage guide is missing from this install ({path}). Reinstall camoufox-cli.")
|
|
39
|
+
return (
|
|
40
|
+
f"[camoufox-cli:skill] {topic} guide v{version}\n\n"
|
|
41
|
+
f"{body.strip()}\n\n"
|
|
42
|
+
f"[camoufox-cli:skill] end of {topic} guide v{version}\n"
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def unknown_command_message(action: str, version: str) -> str:
|
|
47
|
+
"""Error text for an unknown command, with a hint for agents whose skill is stale."""
|
|
48
|
+
lines = [f"Unknown command: {action}"]
|
|
49
|
+
if action.startswith("-") and " " in action:
|
|
50
|
+
# e.g. T="--tab x"; camoufox-cli $T ... (zsh does not split $T into words)
|
|
51
|
+
lines.append(
|
|
52
|
+
f"`{action}` reached camoufox-cli as one argument. Pass the flag and its value "
|
|
53
|
+
"as two arguments. zsh does not split an unquoted $VAR into words."
|
|
54
|
+
)
|
|
55
|
+
return "\n".join(lines)
|
|
56
|
+
if action in REMOVED_COMMANDS:
|
|
57
|
+
lines.append(f"`{action}` was removed: {REMOVED_COMMANDS[action]}.")
|
|
58
|
+
lines.append(
|
|
59
|
+
f"If a skill or guide told you to run this, it may not match camoufox-cli v{version}. "
|
|
60
|
+
"Run `camoufox-cli skill` to read the guide for this version."
|
|
61
|
+
)
|
|
62
|
+
return "\n".join(lines)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|