camoufox-cli 0.4.0__tar.gz → 0.5.0__tar.gz

camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "camoufox-cli",
+  "owner": {
+    "name": "Benn Huang"
+  },
+  "metadata": {
+    "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Camoufox",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "camoufox-cli",
+      "description": "Anti-detect browser automation skill with fingerprint spoofing for AI agents",
+      "source": "./",
+      "skills": [
+        "./skills/camoufox-cli"
+      ]
+    }
+  ]
+}

{camoufox_cli-0.4.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/src/browser.ts

@@ -8,6 +8,8 @@ import { loadOrCreate, toLaunchOptions } from "./identity.js";
 import { parseProxySettings } from "./proxy.js";
 import { RefRegistry } from "./refs.js";
 
+const MAX_HISTORY = 200;
+
 function ensureBrowserInstalled(): void {
   try {
     execFileSync("npx", ["camoufox-js", "path"], { stdio: "pipe" });
@@ -147,6 +149,9 @@ export class BrowserManager {
   pushHistory(url: string): void {
     this.history = this.history.slice(0, this.historyIndex + 1);
     this.history.push(url);
+    if (this.history.length > MAX_HISTORY) {
+      this.history = this.history.slice(-MAX_HISTORY);
+    }
     this.historyIndex = this.history.length - 1;
   }
 

{camoufox_cli-0.4.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/src/camoufox_cli/browser.py

@@ -13,6 +13,9 @@ from .proxy import parse_proxy_settings
 from .refs import RefRegistry
 
 
+_MAX_HISTORY = 200
+
+
 def _ensure_browser_installed() -> None:
     """Check that the Camoufox browser binary is installed, raise if not."""
     try:
@@ -147,6 +150,9 @@ class BrowserManager:
         # Truncate forward history when navigating to a new page
         self._history = self._history[:self._history_index + 1]
         self._history.append(url)
+        # Cap history to avoid unbounded growth in long-lived daemons.
+        if len(self._history) > _MAX_HISTORY:
+            self._history = self._history[-_MAX_HISTORY:]
         self._history_index = len(self._history) - 1
 
     def go_back(self) -> str | None:

camoufox_cli-0.5.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+uv.lock
+
+# Node
+node_modules/
+js/README.md
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Env
+.env
+
+# Runtime
+*.sock
+*.pid

camoufox_cli-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benn Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

camoufox_cli-0.5.0/Makefile

@@ -0,0 +1,30 @@
+.PHONY: test test-unit test-integration test-e2e build publish publish-pip publish-npm clean
+
+test:
+	python -m pytest tests/ -v
+
+test-unit:
+	python -m pytest tests/ -v -m "not integration"
+
+test-integration:
+	python -m pytest tests/ -v -m integration
+
+test-e2e:
+	python -m pytest tests/test_e2e.py -v
+	cd js && npx vitest run tests/e2e.test.ts
+
+build: clean
+	uv build
+	cd js && npm run build
+
+publish: publish-pip publish-npm
+
+publish-pip: build
+	uvx twine upload dist/*
+
+publish-npm: build
+	cd js && npm publish --access public
+
+clean:
+	rm -rf dist/
+	rm -rf js/dist/

{camoufox_cli-0.4.0 → camoufox_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: camoufox-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Anti-detect browser CLI & Skills for AI agents, powered by Camoufox
 Project-URL: Homepage, https://github.com/Bin-Huang/camoufox-cli
 Project-URL: Repository, https://github.com/Bin-Huang/camoufox-cli
@@ -180,6 +180,33 @@ camoufox-cli cookies export file.json     # Export cookies
 --locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
 ```
 
+## Config File
+
+Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cli/config.json` (override the path with `$CAMOUFOX_CLI_CONFIG`):
+
+```json
+{
+  "default": {
+    "persistent": true,
+    "timeout": 3600,
+    "proxy": "http://user:pass@host:8080"
+  },
+  "sessions": {
+    "<your-session-name>": {
+      "proxy": "socks5://127.0.0.1:1080",
+      "locale": "zh-CN"
+    }
+  }
+}
+```
+
+- **`default`** applies to every session.
+- **`sessions` is optional.** You never pre-register sessions — the name is just whatever you pass to `--session`. A `sessions.<name>` block only kicks in when you happen to run `--session <name>`, layering its keys on top of `default`; any other session (or no `--session` at all) just uses `default`. Above, `camoufox-cli --session <your-session-name> open <url>` swaps in that block's proxy + locale, while every other session keeps the `default` proxy.
+- **Command-line flags always win** over the file, which in turn wins over built-in defaults.
+- Settable keys: `proxy`, `locale`, `geoip`, `persistent` (`true` / `false` / path string), `headed`, `timeout`, `json`. `session` is command-line only (it selects which block to apply), and per-command options like `--full` or `-i` are never read from config.
+- A broken config never blocks a command — it's ignored with a warning on stderr.
+- Config is read when a session's daemon **first launches**. If one is already running for that session, run `camoufox-cli --session <name> close` first for changes to take effect.
+
 ## Persistent Identity
 
 Without `--persistent`, every launch gets a fresh random fingerprint. With `--persistent`, a `camoufox-cli.json` file is written next to the browser's user data. Fingerprint, OS, and canvas/font seeds are generated on the first launch and frozen afterwards; locale and proxy-derived timezone/geolocation are also saved but track whatever you pass on the command line. Every subsequent launch with the same path reloads the identity, so sites see the same device on every visit.

camoufox_cli-0.5.0/README.md

@@ -0,0 +1,253 @@
+# camoufox-cli
+
+Anti-detect browser CLI & Skills for AI agents, powered by [Camoufox](https://github.com/daijro/camoufox).
+
+### Highlights
+
+- C++-level fingerprint spoofing via Camoufox (canvas, WebGL, audio, screen metrics, fonts)
+- Persistent identities: stable fingerprint, OS, and locale across launches with `--persistent`
+- Accessibility-tree snapshots with `@ref` element targeting
+- Session isolation with cookie import/export
+- Shell commands, no code generation
+
+### Works with
+
+OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.
+
+## Install
+
+Tell your AI agent (e.g. OpenClaw):
+
+> Install this CLI and skills from https://github.com/Bin-Huang/camoufox-cli
+
+Or install manually:
+
+```bash
+npm install -g camoufox-cli
+camoufox-cli install              # Download browser
+```
+
+Or with pip:
+
+```bash
+pipx install camoufox-cli
+camoufox-cli install              # Download browser
+```
+
+On Linux, install system dependencies with:
+
+```bash
+camoufox-cli install --with-deps
+```
+
+### Agent Skill
+
+```bash
+# Add skills for AI agents (Claude Code, Cursor, Codex, etc.)
+npx skills add Bin-Huang/camoufox-cli
+```
+
+## Quick Start
+
+```bash
+camoufox-cli open https://example.com    # Launch browser & navigate
+camoufox-cli snapshot -i                  # Interactive elements only
+# - link "More information..." [ref=e1]
+camoufox-cli click @e1                    # Click by ref
+camoufox-cli close                        # Done
+```
+
+## Commands
+
+### Navigation
+
+```bash
+camoufox-cli open <url>                   # Navigate to URL (starts daemon if needed)
+camoufox-cli back                         # Go back
+camoufox-cli forward                      # Go forward
+camoufox-cli reload                       # Reload page
+camoufox-cli url                          # Print current URL
+camoufox-cli title                        # Print page title
+camoufox-cli close                        # Close browser and stop daemon
+```
+
+### Snapshot
+
+```bash
+camoufox-cli snapshot                     # Full accessibility tree
+camoufox-cli snapshot -i                  # Interactive elements only
+camoufox-cli snapshot -s "css-selector"   # Scoped to CSS selector
+```
+
+Output format:
+
+```
+- heading "Example Domain" [level=1] [ref=e1]
+- paragraph [ref=e2]
+  - link "More information..." [ref=e3]
+```
+
+### Interaction
+
+```bash
+camoufox-cli click @e1                    # Click element
+camoufox-cli fill @e3 "search query"      # Clear + type into input
+camoufox-cli type @e3 "append text"       # Type without clearing
+camoufox-cli select @e5 "option text"     # Select dropdown option
+camoufox-cli check @e6                    # Toggle checkbox
+camoufox-cli hover @e2                    # Hover over element
+camoufox-cli press Enter                  # Press keyboard key
+camoufox-cli press "Control+a"            # Key combination
+```
+
+### Data Extraction
+
+```bash
+camoufox-cli text @e1                     # Get text content of element
+camoufox-cli text body                    # Get all page text
+camoufox-cli eval "document.title"        # Execute JavaScript
+camoufox-cli screenshot                   # Screenshot (JSON with base64)
+camoufox-cli screenshot page.png          # Screenshot to file
+camoufox-cli screenshot --full page.png   # Full page screenshot
+```
+
+### Scroll & Wait
+
+```bash
+camoufox-cli scroll down                  # Scroll down 500px
+camoufox-cli scroll up 1000               # Scroll up 1000px
+camoufox-cli wait 2000                    # Wait milliseconds
+camoufox-cli wait @e1                     # Wait for element to appear
+camoufox-cli wait --url "*/dashboard"     # Wait for URL pattern
+```
+
+### Tabs
+
+```bash
+camoufox-cli tabs                         # List open tabs
+camoufox-cli switch 2                     # Switch to tab by index
+camoufox-cli close-tab                    # Close current tab
+```
+
+### Sessions
+
+```bash
+camoufox-cli sessions                     # List active sessions
+camoufox-cli --session work open <url>    # Use named session
+camoufox-cli close --all                  # Close all sessions
+```
+
+### Cookies
+
+```bash
+camoufox-cli cookies                      # Dump cookies as JSON
+camoufox-cli cookies import file.json     # Import cookies
+camoufox-cli cookies export file.json     # Export cookies
+```
+
+## Flags
+
+```
+--session <name>       Named session (default: "default")
+--headed               Show browser window (default: headless)
+--timeout <seconds>    Daemon idle timeout (default: 1800)
+--json                 Output as JSON
+--persistent [path]    Persistent identity (see below); default path: ~/.camoufox-cli/profiles/<session>
+--proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
+--no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
+--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
+```
+
+## Config File
+
+Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cli/config.json` (override the path with `$CAMOUFOX_CLI_CONFIG`):
+
+```json
+{
+  "default": {
+    "persistent": true,
+    "timeout": 3600,
+    "proxy": "http://user:pass@host:8080"
+  },
+  "sessions": {
+    "<your-session-name>": {
+      "proxy": "socks5://127.0.0.1:1080",
+      "locale": "zh-CN"
+    }
+  }
+}
+```
+
+- **`default`** applies to every session.
+- **`sessions` is optional.** You never pre-register sessions — the name is just whatever you pass to `--session`. A `sessions.<name>` block only kicks in when you happen to run `--session <name>`, layering its keys on top of `default`; any other session (or no `--session` at all) just uses `default`. Above, `camoufox-cli --session <your-session-name> open <url>` swaps in that block's proxy + locale, while every other session keeps the `default` proxy.
+- **Command-line flags always win** over the file, which in turn wins over built-in defaults.
+- Settable keys: `proxy`, `locale`, `geoip`, `persistent` (`true` / `false` / path string), `headed`, `timeout`, `json`. `session` is command-line only (it selects which block to apply), and per-command options like `--full` or `-i` are never read from config.
+- A broken config never blocks a command — it's ignored with a warning on stderr.
+- Config is read when a session's daemon **first launches**. If one is already running for that session, run `camoufox-cli --session <name> close` first for changes to take effect.
+
+## Persistent Identity
+
+Without `--persistent`, every launch gets a fresh random fingerprint. With `--persistent`, a `camoufox-cli.json` file is written next to the browser's user data. Fingerprint, OS, and canvas/font seeds are generated on the first launch and frozen afterwards; locale and proxy-derived timezone/geolocation are also saved but track whatever you pass on the command line. Every subsequent launch with the same path reloads the identity, so sites see the same device on every visit.
+
+```bash
+# First launch: generates + stores identity
+camoufox-cli --persistent ~/.camoufox-cli/profiles/alice open https://example.com
+
+# Every subsequent launch: same fingerprint, same cookies, same device
+camoufox-cli --persistent ~/.camoufox-cli/profiles/alice open https://example.com
+```
+
+**Frozen** — generated on the first launch, permanent until the directory is deleted:
+
+- Fingerprint (UA, canvas, WebGL, fonts, navigator properties)
+- OS (defaults to host OS)
+- Canvas/font noise seeds
+
+**Persisted** — stored in the file, refreshed whenever you pass the flag:
+
+- `--locale`: sets the stored locale; pass it again to change it, omit it to keep the stored value.
+- Timezone / geolocation: re-derived from the current proxy's IP whenever `--proxy` is active (and `--no-geoip` isn't set), then written back. Without a proxy, the last stored values stay in effect.
+
+**Per-launch** — never stored; pass on every launch for it to apply:
+
+- `--proxy`: proxies rotate or expire; re-specify each launch to avoid silently running through a stale one.
+- `--no-geoip`: follows the current `--proxy`.
+
+**Multiple identities in parallel.** Each persistent path is a distinct identity. Combine with `--session` for concurrent daemons:
+
+```bash
+camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://...
+camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://...
+```
+
+**Resetting an identity.** Just delete the directory (`rm -rf ~/.camoufox-cli/profiles/alice`). The next launch generates a fresh one.
+
+## Architecture
+
+```
+CLI (camoufox-cli)  ──Unix socket──▶  Daemon (Python)  ──Playwright──▶  Camoufox (Firefox)
+```
+
+The CLI sends JSON commands to a long-running daemon process via Unix socket. The daemon manages the Camoufox browser instance and maintains the ref registry between commands. The daemon auto-starts on the first command and auto-stops after 30 minutes of inactivity.
+
+## Related
+
+- [google-analytics-cli](https://github.com/Bin-Huang/google-analytics-cli) -- Google Analytics CLI & Skills for AI agents (and humans)
+- [google-search-console-cli](https://github.com/Bin-Huang/google-search-console-cli) -- Google Search Console CLI & Skills for AI agents (and humans)
+- [youtube-analytics-cli](https://github.com/Bin-Huang/youtube-analytics-cli) -- YouTube Analytics CLI & Skills for AI agents (and humans)
+- [x-analytics-cli](https://github.com/Bin-Huang/x-analytics-cli) -- X Analytics CLI & Skills for AI agents (and humans)
+- [google-ads-open-cli](https://github.com/Bin-Huang/google-ads-open-cli) -- Google Ads CLI & Skills for AI agents (and humans)
+- [meta-ads-open-cli](https://github.com/Bin-Huang/meta-ads-open-cli) -- Meta Ads CLI & Skills for AI agents (and humans)
+- [microsoft-ads-cli](https://github.com/Bin-Huang/microsoft-ads-cli) -- Microsoft Ads CLI & Skills for AI agents (and humans)
+- [amazon-ads-open-cli](https://github.com/Bin-Huang/amazon-ads-open-cli) -- Amazon Ads CLI & Skills for AI agents (and humans)
+- [tiktok-ads-cli](https://github.com/Bin-Huang/tiktok-ads-cli) -- TikTok Ads CLI & Skills for AI agents (and humans)
+- [linkedin-ads-cli](https://github.com/Bin-Huang/linkedin-ads-cli) -- LinkedIn Ads CLI & Skills for AI agents (and humans)
+- [x-ads-cli](https://github.com/Bin-Huang/x-ads-cli) -- X Ads CLI & Skills for AI agents (and humans)
+- [snapchat-ads-cli](https://github.com/Bin-Huang/snapchat-ads-cli) -- Snapchat Ads CLI & Skills for AI agents (and humans)
+- [pinterest-ads-cli](https://github.com/Bin-Huang/pinterest-ads-cli) -- Pinterest Ads CLI & Skills for AI agents (and humans)
+- [reddit-ads-cli](https://github.com/Bin-Huang/reddit-ads-cli) -- Reddit Ads CLI & Skills for AI agents (and humans)
+- [spotify-ads-cli](https://github.com/Bin-Huang/spotify-ads-cli) -- Spotify Ads CLI & Skills for AI agents (and humans)
+- [apple-ads-cli](https://github.com/Bin-Huang/apple-ads-cli) -- Apple Ads CLI & Skills for AI agents (and humans)
+## License
+
+MIT

camoufox_cli-0.5.0/js/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

camoufox_cli-0.5.0/js/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benn Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.