camoufox-cli 0.7.0__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 (62) hide show
  1. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/.gitignore +2 -0
  2. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/PKG-INFO +43 -12
  3. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/README.md +40 -9
  4. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/pyproject.toml +19 -2
  5. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/cli.py +166 -24
  6. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/commands.py +75 -11
  7. {camoufox_cli-0.7.0/skills/camoufox-cli/references → camoufox_cli-0.8.0/src/camoufox_cli/guide}/commands.md +11 -7
  8. {camoufox_cli-0.7.0/skills/camoufox-cli/references → camoufox_cli-0.8.0/src/camoufox_cli/guide}/snapshot-refs.md +1 -1
  9. camoufox_cli-0.7.0/skills/camoufox-cli/SKILL.md → camoufox_cli-0.8.0/src/camoufox_cli/guide/usage.md +30 -13
  10. camoufox_cli-0.8.0/src/camoufox_cli/install.py +196 -0
  11. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/refs.py +38 -11
  12. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/server.py +6 -0
  13. camoufox_cli-0.8.0/src/camoufox_cli/skill.py +62 -0
  14. camoufox_cli-0.7.0/.claude-plugin/marketplace.json +0 -20
  15. camoufox_cli-0.7.0/Makefile +0 -30
  16. camoufox_cli-0.7.0/js/.gitignore +0 -2
  17. camoufox_cli-0.7.0/js/LICENSE +0 -21
  18. camoufox_cli-0.7.0/js/package-lock.json +0 -2785
  19. camoufox_cli-0.7.0/js/package.json +0 -47
  20. camoufox_cli-0.7.0/js/pnpm-lock.yaml +0 -1599
  21. camoufox_cli-0.7.0/js/scripts/postinstall.js +0 -11
  22. camoufox_cli-0.7.0/js/src/browser.ts +0 -371
  23. camoufox_cli-0.7.0/js/src/cli.ts +0 -520
  24. camoufox_cli-0.7.0/js/src/commands.ts +0 -364
  25. camoufox_cli-0.7.0/js/src/config.ts +0 -140
  26. camoufox_cli-0.7.0/js/src/daemon.ts +0 -27
  27. camoufox_cli-0.7.0/js/src/identity.ts +0 -206
  28. camoufox_cli-0.7.0/js/src/install.ts +0 -126
  29. camoufox_cli-0.7.0/js/src/protocol.ts +0 -32
  30. camoufox_cli-0.7.0/js/src/proxy.ts +0 -40
  31. camoufox_cli-0.7.0/js/src/refs.ts +0 -65
  32. camoufox_cli-0.7.0/js/src/server.ts +0 -200
  33. camoufox_cli-0.7.0/js/tests/browser.test.ts +0 -98
  34. camoufox_cli-0.7.0/js/tests/cli.test.ts +0 -466
  35. camoufox_cli-0.7.0/js/tests/commands.test.ts +0 -189
  36. camoufox_cli-0.7.0/js/tests/e2e.test.ts +0 -294
  37. camoufox_cli-0.7.0/js/tests/install.test.ts +0 -153
  38. camoufox_cli-0.7.0/js/tests/protocol.test.ts +0 -98
  39. camoufox_cli-0.7.0/js/tests/proxy.test.ts +0 -55
  40. camoufox_cli-0.7.0/js/tests/refs.test.ts +0 -150
  41. camoufox_cli-0.7.0/js/tests/server.test.ts +0 -257
  42. camoufox_cli-0.7.0/js/tsconfig.json +0 -14
  43. camoufox_cli-0.7.0/js/vitest.config.ts +0 -7
  44. camoufox_cli-0.7.0/src/camoufox_cli/install.py +0 -127
  45. camoufox_cli-0.7.0/tests/__init__.py +0 -0
  46. camoufox_cli-0.7.0/tests/fixture.html +0 -22
  47. camoufox_cli-0.7.0/tests/test_cli.py +0 -402
  48. camoufox_cli-0.7.0/tests/test_commands.py +0 -556
  49. camoufox_cli-0.7.0/tests/test_e2e.py +0 -302
  50. camoufox_cli-0.7.0/tests/test_install.py +0 -150
  51. camoufox_cli-0.7.0/tests/test_protocol.py +0 -63
  52. camoufox_cli-0.7.0/tests/test_proxy.py +0 -37
  53. camoufox_cli-0.7.0/tests/test_refs.py +0 -112
  54. camoufox_cli-0.7.0/tests/test_server.py +0 -101
  55. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/LICENSE +0 -0
  56. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/__init__.py +0 -0
  57. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/__main__.py +0 -0
  58. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/browser.py +0 -0
  59. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/config.py +0 -0
  60. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/identity.py +0 -0
  61. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/protocol.py +0 -0
  62. {camoufox_cli-0.7.0 → camoufox_cli-0.8.0}/src/camoufox_cli/proxy.py +0 -0
@@ -12,8 +12,10 @@ uv.lock
12
12
  # Node
13
13
  node_modules/
14
14
  js/README.md
15
+ js/guide/
15
16
 
16
17
  # IDE
18
+ .claude/
17
19
  .idea/
18
20
  .vscode/
19
21
  *.swp
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: camoufox-cli
3
- Version: 0.7.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
@@ -15,15 +15,35 @@ Classifier: Intended Audience :: Developers
15
15
  Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
16
16
  Classifier: Topic :: Software Development :: Testing
17
17
  Requires-Python: >=3.10
18
- Requires-Dist: camoufox[geoip]
18
+ Requires-Dist: camoufox[geoip]==0.4.11
19
19
  Requires-Dist: pillow
20
20
  Requires-Dist: playwright==1.52.0
21
21
  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)
@@ -45,7 +65,7 @@ Tell your AI agent (e.g. OpenClaw):
45
65
  Or install manually:
46
66
 
47
67
  ```bash
48
- npm install -g camoufox-cli
68
+ npm install -g camoufox-cli # Requires Node.js 20.10+
49
69
  camoufox-cli install # Download browser
50
70
  ```
51
71
 
@@ -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
@@ -122,10 +145,16 @@ camoufox-cli type @e3 "append text" # Type without clearing
122
145
  camoufox-cli select @e5 "option text" # Select dropdown option
123
146
  camoufox-cli check @e6 # Toggle checkbox
124
147
  camoufox-cli hover @e2 # Hover over element
148
+ camoufox-cli mouse click 660 380 # Click at viewport coordinates
125
149
  camoufox-cli press Enter # Press keyboard key
126
150
  camoufox-cli press "Control+a" # Key combination
127
151
  ```
128
152
 
153
+ `mouse click` reaches elements that have no ref, such as a checkbox inside a
154
+ cross-origin iframe (for example a Cloudflare Turnstile widget). Coordinates are
155
+ viewport CSS pixels. At the default `devicePixelRatio` of 1, they equal the pixels
156
+ of a non-`--full` screenshot.
157
+
129
158
  ### Data Extraction
130
159
 
131
160
  ```bash
@@ -196,6 +225,7 @@ camoufox-cli cookies export file.json # Export cookies
196
225
  --proxy <url> Proxy server (http:// or https://; auth: http://user:pass@host:port)
197
226
  --no-geoip Disable automatic GeoIP spoofing (auto-enabled with --proxy)
198
227
  --locale <tag> Force browser locale (e.g. "en-US" or "en-US,zh-CN")
228
+ --version Print version and exit
199
229
  ```
200
230
 
201
231
  ## Config File
@@ -211,7 +241,7 @@ Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cl
211
241
  },
212
242
  "sessions": {
213
243
  "<your-session-name>": {
214
- "proxy": "socks5://127.0.0.1:1080",
244
+ "proxy": "http://user:pass@proxy.example.com:8080",
215
245
  "locale": "zh-CN"
216
246
  }
217
247
  }
@@ -265,7 +295,7 @@ camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob open https:
265
295
  ## Architecture
266
296
 
267
297
  ```
268
- CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python) ──Playwright──▶ Camoufox (Firefox)
298
+ CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python / Node) ──Playwright──▶ Camoufox (Firefox)
269
299
  ```
270
300
 
271
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.
@@ -288,6 +318,7 @@ The CLI sends JSON commands to a long-running daemon process via Unix socket. Th
288
318
  - [reddit-ads-cli](https://github.com/Bin-Huang/reddit-ads-cli) -- Reddit Ads CLI & Skills for AI agents (and humans)
289
319
  - [spotify-ads-cli](https://github.com/Bin-Huang/spotify-ads-cli) -- Spotify Ads CLI & Skills for AI agents (and humans)
290
320
  - [apple-ads-cli](https://github.com/Bin-Huang/apple-ads-cli) -- Apple Ads CLI & Skills for AI agents (and humans)
321
+
291
322
  ## License
292
323
 
293
324
  MIT
@@ -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)
@@ -23,7 +43,7 @@ Tell your AI agent (e.g. OpenClaw):
23
43
  Or install manually:
24
44
 
25
45
  ```bash
26
- npm install -g camoufox-cli
46
+ npm install -g camoufox-cli # Requires Node.js 20.10+
27
47
  camoufox-cli install # Download browser
28
48
  ```
29
49
 
@@ -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
@@ -100,10 +123,16 @@ camoufox-cli type @e3 "append text" # Type without clearing
100
123
  camoufox-cli select @e5 "option text" # Select dropdown option
101
124
  camoufox-cli check @e6 # Toggle checkbox
102
125
  camoufox-cli hover @e2 # Hover over element
126
+ camoufox-cli mouse click 660 380 # Click at viewport coordinates
103
127
  camoufox-cli press Enter # Press keyboard key
104
128
  camoufox-cli press "Control+a" # Key combination
105
129
  ```
106
130
 
131
+ `mouse click` reaches elements that have no ref, such as a checkbox inside a
132
+ cross-origin iframe (for example a Cloudflare Turnstile widget). Coordinates are
133
+ viewport CSS pixels. At the default `devicePixelRatio` of 1, they equal the pixels
134
+ of a non-`--full` screenshot.
135
+
107
136
  ### Data Extraction
108
137
 
109
138
  ```bash
@@ -174,6 +203,7 @@ camoufox-cli cookies export file.json # Export cookies
174
203
  --proxy <url> Proxy server (http:// or https://; auth: http://user:pass@host:port)
175
204
  --no-geoip Disable automatic GeoIP spoofing (auto-enabled with --proxy)
176
205
  --locale <tag> Force browser locale (e.g. "en-US" or "en-US,zh-CN")
206
+ --version Print version and exit
177
207
  ```
178
208
 
179
209
  ## Config File
@@ -189,7 +219,7 @@ Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cl
189
219
  },
190
220
  "sessions": {
191
221
  "<your-session-name>": {
192
- "proxy": "socks5://127.0.0.1:1080",
222
+ "proxy": "http://user:pass@proxy.example.com:8080",
193
223
  "locale": "zh-CN"
194
224
  }
195
225
  }
@@ -243,7 +273,7 @@ camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob open https:
243
273
  ## Architecture
244
274
 
245
275
  ```
246
- CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python) ──Playwright──▶ Camoufox (Firefox)
276
+ CLI (camoufox-cli) ──Unix socket──▶ Daemon (Python / Node) ──Playwright──▶ Camoufox (Firefox)
247
277
  ```
248
278
 
249
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.
@@ -266,6 +296,7 @@ The CLI sends JSON commands to a long-running daemon process via Unix socket. Th
266
296
  - [reddit-ads-cli](https://github.com/Bin-Huang/reddit-ads-cli) -- Reddit Ads CLI & Skills for AI agents (and humans)
267
297
  - [spotify-ads-cli](https://github.com/Bin-Huang/spotify-ads-cli) -- Spotify Ads CLI & Skills for AI agents (and humans)
268
298
  - [apple-ads-cli](https://github.com/Bin-Huang/apple-ads-cli) -- Apple Ads CLI & Skills for AI agents (and humans)
299
+
269
300
  ## License
270
301
 
271
302
  MIT
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "camoufox-cli"
3
- version = "0.7.0"
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"
@@ -15,7 +15,12 @@ classifiers = [
15
15
  "Topic :: Software Development :: Testing",
16
16
  ]
17
17
  dependencies = [
18
- "camoufox[geoip]",
18
+ # Pin camoufox exactly: it is coupled to the playwright version and the
19
+ # Camoufox browser build, and its module layout shifts between releases
20
+ # (0.5.x dropped camoufox.locale, which install uses). An unpinned dep
21
+ # resolves to the latest on every fresh `pip install` and breaks without
22
+ # warning; keep it in lockstep with playwright below.
23
+ "camoufox[geoip]==0.4.11",
19
24
  "playwright==1.52.0",
20
25
  "Pillow",
21
26
  ]
@@ -32,6 +37,18 @@ camoufox-cli = "camoufox_cli.cli:main"
32
37
  requires = ["hatchling"]
33
38
  build-backend = "hatchling.build"
34
39
 
40
+ [tool.hatch.build.targets.sdist]
41
+ # List the sdist contents explicitly. By default hatchling packs every file
42
+ # that the repo .gitignore does not exclude, which picks up local untracked
43
+ # files and the JS package. A leading "/" anchors each pattern to the repo
44
+ # root, so js/LICENSE does not match.
45
+ include = [
46
+ "/src/camoufox_cli",
47
+ "/README.md",
48
+ "/LICENSE",
49
+ "/pyproject.toml",
50
+ ]
51
+
35
52
  [tool.hatch.build.targets.wheel]
36
53
  packages = ["src/camoufox_cli"]
37
54
 
@@ -7,18 +7,41 @@ import os
7
7
  import socket
8
8
  import subprocess
9
9
  import sys
10
+ import tempfile
10
11
  import time
11
12
 
12
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
+ )
13
17
 
14
18
 
15
19
  SOCKET_PREFIX = "/tmp/camoufox-cli-"
20
+ # A unix socket path must fit in sun_path: 104 bytes on macOS (108 on Linux),
21
+ # including the terminating NUL.
22
+ _MAX_SOCKET_PATH_BYTES = 103
16
23
 
17
24
 
18
25
  def get_socket_path(session: str) -> str:
19
26
  return f"{SOCKET_PREFIX}{session}.sock"
20
27
 
21
28
 
29
+ def session_name_error(session: str) -> str | None:
30
+ """Why ``session`` cannot be used as a session name, or None if it can.
31
+
32
+ The name becomes part of the daemon's /tmp socket, pid and lock file names
33
+ and of the default --persistent profile path.
34
+ """
35
+ if session in ("", ".", ".."):
36
+ return "must be a non-empty name other than '.' or '..'"
37
+ if "/" in session:
38
+ return "must not contain '/'"
39
+ max_bytes = _MAX_SOCKET_PATH_BYTES - len(get_socket_path("").encode())
40
+ if len(session.encode()) > max_bytes:
41
+ return f"must be at most {max_bytes} bytes (unix socket path limit)"
42
+ return None
43
+
44
+
22
45
  def send_command(sock_path: str, command: dict) -> dict:
23
46
  s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
24
47
  s.connect(sock_path)
@@ -47,21 +70,30 @@ def spawn_daemon(session: str, headed: bool, timeout: int, persistent: str | Non
47
70
  if locale:
48
71
  cmd.extend(["--locale", locale])
49
72
 
50
- subprocess.Popen(
51
- cmd,
52
- stdin=subprocess.DEVNULL,
53
- stdout=subprocess.DEVNULL,
54
- stderr=subprocess.DEVNULL,
55
- start_new_session=True,
56
- )
73
+ # The daemon writes stderr to an anonymous temp file, so a failed start can
74
+ # report its real cause instead of only a timeout.
75
+ with tempfile.TemporaryFile() as err:
76
+ subprocess.Popen(
77
+ cmd,
78
+ stdin=subprocess.DEVNULL,
79
+ stdout=subprocess.DEVNULL,
80
+ stderr=err,
81
+ start_new_session=True,
82
+ )
83
+
84
+ sock_path = get_socket_path(session)
85
+ for _ in range(50):
86
+ if os.path.exists(sock_path):
87
+ return
88
+ time.sleep(0.1)
57
89
 
58
- sock_path = get_socket_path(session)
59
- for _ in range(50):
60
- if os.path.exists(sock_path):
61
- return
62
- time.sleep(0.1)
90
+ # pread: the daemon shares this file's offset, so do not seek it.
91
+ output = os.pread(err.fileno(), os.fstat(err.fileno()).st_size, 0)
63
92
 
64
93
  print("Error: Daemon did not start within 5 seconds", file=sys.stderr)
94
+ output_lines = output.decode(errors="replace").strip().splitlines()
95
+ if output_lines:
96
+ print("Daemon output:\n" + "\n".join(output_lines[-20:]), file=sys.stderr)
65
97
  sys.exit(1)
66
98
 
67
99
 
@@ -91,6 +123,16 @@ def ensure_daemon(session: str, headed: bool, timeout: int, persistent: str | No
91
123
  spawn_daemon(session, headed, timeout, persistent, proxy, geoip, locale)
92
124
 
93
125
 
126
+ def get_version() -> str:
127
+ """Version from installed package metadata; pyproject isn't shipped in the wheel."""
128
+ from importlib.metadata import version, PackageNotFoundError
129
+
130
+ try:
131
+ return version("camoufox-cli")
132
+ except PackageNotFoundError:
133
+ return "unknown"
134
+
135
+
94
136
  def list_sessions() -> list[str]:
95
137
  sessions = []
96
138
  try:
@@ -170,6 +212,10 @@ def parse_args(args: list[str]) -> tuple[dict, dict]:
170
212
 
171
213
  # session selects which config block applies, so it comes only from the CLI.
172
214
  session = cli.get("session", builtin["session"])
215
+ error = session_name_error(session)
216
+ if error:
217
+ print(f"Error: invalid --session {session!r}: {error}", file=sys.stderr)
218
+ sys.exit(1)
173
219
  flags = {**builtin, **load_defaults(session), **cli}
174
220
 
175
221
  action = rest[0]
@@ -181,6 +227,11 @@ def parse_args(args: list[str]) -> tuple[dict, dict]:
181
227
 
182
228
  def build_command(action: str, rest: list[str]) -> dict:
183
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)
184
235
  match action:
185
236
  # Navigation
186
237
  case "open":
@@ -234,6 +285,18 @@ def build_command(action: str, rest: list[str]) -> dict:
234
285
  case "hover":
235
286
  ref = _require(rest, 1, "Usage: camoufox-cli hover @e1")
236
287
  return {"id": "r1", "action": "hover", "params": {"ref": ref}}
288
+ case "mouse":
289
+ usage = "Usage: camoufox-cli mouse click <x> <y>"
290
+ if _require(rest, 1, usage) != "click":
291
+ print(usage, file=sys.stderr)
292
+ sys.exit(1)
293
+ try:
294
+ x = float(_require(rest, 2, usage))
295
+ y = float(_require(rest, 3, usage))
296
+ except ValueError:
297
+ print(usage, file=sys.stderr)
298
+ sys.exit(1)
299
+ return {"id": "r1", "action": "mouse_click", "params": {"x": x, "y": y}}
237
300
  case "press":
238
301
  key = _require(rest, 1, "Usage: camoufox-cli press Enter")
239
302
  return {"id": "r1", "action": "press", "params": {"key": key}}
@@ -297,8 +360,19 @@ def build_command(action: str, rest: list[str]) -> dict:
297
360
  else:
298
361
  return {"id": "r1", "action": "cookies", "params": {"op": "list"}}
299
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
+
300
374
  case _:
301
- 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)
302
376
  sys.exit(1)
303
377
 
304
378
 
@@ -348,7 +422,7 @@ _APT_DEPS = [
348
422
  "libatk1.0-0", "libcairo-gobject2", "libcairo2", "libgdk-pixbuf-2.0-0",
349
423
  "libxrender1", "libfreetype6", "libfontconfig1", "libdbus-1-3",
350
424
  "libnss3", "libnspr4", "libatk-bridge2.0-0", "libdrm2", "libxkbcommon0",
351
- "libatspi2.0-0", "libcups2", "libxshmfence1", "libgbm1",
425
+ "libatspi2.0-0", "libcups2", "libxshmfence1", "libgbm1", "libasound2",
352
426
  ]
353
427
 
354
428
  _DNF_DEPS = [
@@ -365,13 +439,49 @@ _YUM_DEPS = [
365
439
  ]
366
440
 
367
441
 
368
- def _resolve_apt_libasound() -> str:
369
- """Newer Debian/Ubuntu renamed libasound2 to libasound2t64."""
442
+ def _apt_installable(pkg: str) -> bool:
443
+ """True when a dry-run install of the package resolves."""
444
+ result = subprocess.run(
445
+ ["apt-get", "install", "-s", "-y", pkg],
446
+ capture_output=True,
447
+ )
448
+ return result.returncode == 0
449
+
450
+
451
+ def _resolve_apt_deps(deps: list[str]) -> list[str]:
452
+ """Map package names to what this system's apt actually knows.
453
+
454
+ Ubuntu 24.04's 64-bit time_t transition renamed many runtime libs with a
455
+ t64 suffix (libasound2 -> libasound2t64, libgtk-3-0 -> libgtk-3-0t64, ...)
456
+ WITHOUT a Provides for the old name, so installing the old names fails.
457
+ Fast path: if the plain list resolves as a whole (Debian, older Ubuntu),
458
+ use it. Otherwise resolve per package, preferring the plain name and
459
+ falling back to <name>t64. Unknown-either-way names are kept so apt
460
+ reports the real error instead of this helper guessing silently.
461
+ """
370
462
  result = subprocess.run(
371
- ["dpkg", "-l", "libasound2t64"],
463
+ ["apt-get", "install", "-s", "-y", *deps],
372
464
  capture_output=True,
373
465
  )
374
- return "libasound2t64" if result.returncode == 0 else "libasound2"
466
+ if result.returncode == 0:
467
+ return deps
468
+ return [
469
+ dep if _apt_installable(dep)
470
+ else (f"{dep}t64" if _apt_installable(f"{dep}t64") else dep)
471
+ for dep in deps
472
+ ]
473
+
474
+
475
+ def _run_as_root(argv: list[str]) -> None:
476
+ """Run a privileged package-manager command.
477
+
478
+ Prefer bare invocation when already root (Docker/CI images rarely ship
479
+ sudo). Fall back to sudo for unprivileged interactive installs.
480
+ """
481
+ if os.geteuid() == 0:
482
+ subprocess.run(argv, check=True)
483
+ else:
484
+ subprocess.run(["sudo", *argv], check=True)
375
485
 
376
486
 
377
487
  def _install_system_deps() -> None:
@@ -385,13 +495,14 @@ def _install_system_deps() -> None:
385
495
  print("[camoufox-cli] Installing system dependencies...", file=sys.stderr)
386
496
 
387
497
  if shutil.which("apt-get"):
388
- deps = [*_APT_DEPS, _resolve_apt_libasound()]
389
- subprocess.run(["sudo", "apt-get", "update", "-y"], check=True)
390
- subprocess.run(["sudo", "apt-get", "install", "-y", *deps], check=True)
498
+ _run_as_root(["apt-get", "update", "-y"])
499
+ # Resolve AFTER update: dry-run resolution needs a populated apt cache.
500
+ deps = _resolve_apt_deps(_APT_DEPS)
501
+ _run_as_root(["apt-get", "install", "-y", *deps])
391
502
  elif shutil.which("dnf"):
392
- subprocess.run(["sudo", "dnf", "install", "-y", *_DNF_DEPS], check=True)
503
+ _run_as_root(["dnf", "install", "-y", *_DNF_DEPS])
393
504
  elif shutil.which("yum"):
394
- subprocess.run(["sudo", "yum", "install", "-y", *_YUM_DEPS], check=True)
505
+ _run_as_root(["yum", "install", "-y", *_YUM_DEPS])
395
506
  else:
396
507
  print("[camoufox-cli] Could not detect a supported package manager (apt-get, dnf, yum).", file=sys.stderr)
397
508
  sys.exit(1)
@@ -401,6 +512,12 @@ def _install_system_deps() -> None:
401
512
 
402
513
  def main():
403
514
  args = sys.argv[1:]
515
+
516
+ # Short-circuit before parse_args: --version has no command and needs no daemon.
517
+ if "--version" in args:
518
+ print(get_version())
519
+ return
520
+
404
521
  flags, command = parse_args(args)
405
522
 
406
523
  # Resolve default persistent path
@@ -419,6 +536,11 @@ def main():
419
536
  _install_system_deps()
420
537
  return
421
538
 
539
+ # Client-side: skill
540
+ if action == "skill":
541
+ sys.stdout.write(render_guide(command["params"]["topic"], get_version()))
542
+ return
543
+
422
544
  # Client-side: sessions
423
545
  if action == "sessions":
424
546
  sessions = list_sessions()
@@ -461,9 +583,24 @@ def main():
461
583
  return
462
584
  except Exception as e:
463
585
  last_err = str(e)
586
+ # close is idempotent: if the daemon is gone (socket removed),
587
+ # there is nothing left to close — that IS success. This is the
588
+ # receipt for a close that raced the last-tab shutdown: the daemon
589
+ # may exit after releasing our tab but before responding.
590
+ if action == "close" and not os.path.exists(sock_path):
591
+ if flags["json"]:
592
+ print(json.dumps({"id": "r1", "success": True, "data": {"closed": True}}))
593
+ return
464
594
  if attempt < 4:
465
595
  time.sleep(0.2 * (attempt + 1))
466
596
 
597
+ # Same idempotent-close check once more: the daemon may have finished
598
+ # unlinking its socket only while we were burning the retry budget.
599
+ if action == "close" and not os.path.exists(sock_path):
600
+ if flags["json"]:
601
+ print(json.dumps({"id": "r1", "success": True, "data": {"closed": True}}))
602
+ return
603
+
467
604
  print(f"Error: Failed to connect to daemon after 5 attempts: {last_err}", file=sys.stderr)
468
605
  sys.exit(1)
469
606
 
@@ -491,6 +628,7 @@ Interaction:
491
628
  select @ref "option" Select dropdown option
492
629
  check @ref Toggle checkbox
493
630
  hover @ref Hover over element
631
+ mouse click <x> <y> Click at viewport coordinates (no ref needed)
494
632
  press <key> Press key (e.g. Enter, Control+a)
495
633
 
496
634
  Data:
@@ -513,6 +651,9 @@ Session:
513
651
 
514
652
  Setup:
515
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
516
657
 
517
658
  Flags:
518
659
  --session <name> Session name (default: "default")
@@ -522,10 +663,11 @@ Flags:
522
663
  --headed Show browser window
523
664
  --timeout <secs> Daemon idle timeout (default: 1800)
524
665
  --json Output as JSON
525
- --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>)
526
667
  --proxy <url> Proxy server (e.g. http://host:port or https://host:443)
527
668
  --no-geoip Disable automatic GeoIP spoofing (auto-enabled with --proxy)
528
669
  --locale <tag> Force browser locale (e.g. "en-US" or "en-US,zh-CN")
670
+ --version Print version and exit
529
671
 
530
672
  Config file:
531
673
  ~/.camoufox-cli/config.json sets defaults for the flags above (override the