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.
Files changed (21) hide show
  1. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/.gitignore +1 -0
  2. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/PKG-INFO +32 -9
  3. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/README.md +31 -8
  4. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/pyproject.toml +1 -1
  5. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/cli.py +29 -2
  6. camoufox_cli-0.8.0/src/camoufox_cli/guide/commands.md +153 -0
  7. camoufox_cli-0.8.0/src/camoufox_cli/guide/snapshot-refs.md +221 -0
  8. camoufox_cli-0.8.0/src/camoufox_cli/guide/usage.md +402 -0
  9. camoufox_cli-0.8.0/src/camoufox_cli/skill.py +62 -0
  10. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/LICENSE +0 -0
  11. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/__init__.py +0 -0
  12. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/__main__.py +0 -0
  13. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/browser.py +0 -0
  14. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/commands.py +0 -0
  15. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/config.py +0 -0
  16. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/identity.py +0 -0
  17. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/install.py +0 -0
  18. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/protocol.py +0 -0
  19. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/proxy.py +0 -0
  20. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/refs.py +0 -0
  21. {camoufox_cli-0.7.6 → camoufox_cli-0.8.0}/src/camoufox_cli/server.py +0 -0
@@ -12,6 +12,7 @@ uv.lock
12
12
  # Node
13
13
  node_modules/
14
14
  js/README.md
15
+ js/guide/
15
16
 
16
17
  # IDE
17
18
  .claude/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: camoufox-cli
3
- Version: 0.7.6
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
+ [![npm](https://img.shields.io/npm/v/camoufox-cli)](https://www.npmjs.com/package/camoufox-cli)
26
+ [![PyPI](https://img.shields.io/pypi/v/camoufox-cli)](https://pypi.org/project/camoufox-cli/)
27
+ [![npm downloads](https://img.shields.io/npm/dm/camoufox-cli)](https://www.npmjs.com/package/camoufox-cli)
28
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
- ## Quick Start
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 open https://example.com # Launch browser & navigate
80
- camoufox-cli snapshot -i # Interactive elements only
81
- # - link "More information..." [ref=e1]
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": "socks5://127.0.0.1:1080",
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
+ [![npm](https://img.shields.io/npm/v/camoufox-cli)](https://www.npmjs.com/package/camoufox-cli)
4
+ [![PyPI](https://img.shields.io/pypi/v/camoufox-cli)](https://pypi.org/project/camoufox-cli/)
5
+ [![npm downloads](https://img.shields.io/npm/dm/camoufox-cli)](https://www.npmjs.com/package/camoufox-cli)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
- ## Quick Start
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 open https://example.com # Launch browser & navigate
58
- camoufox-cli snapshot -i # Interactive elements only
59
- # - link "More information..." [ref=e1]
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": "socks5://127.0.0.1:1080",
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.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "camoufox-cli"
3
- version = "0.7.6"
3
+ version = "0.8.0"
4
4
  description = "Anti-detect browser CLI & Skills for AI agents, powered by Camoufox"
5
5
  requires-python = ">=3.10"
6
6
  license = "MIT"
@@ -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"Unknown command: {action}\n{USAGE}", file=sys.stderr)
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] Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
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