stealth-cli 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,295 @@
+# 🦊 stealth-cli
+
+Anti-detection browser CLI powered by [Camoufox](https://camoufox.com). Browse, screenshot, search, extract, crawl — all with C++ level fingerprint spoofing. Zero JavaScript shims, undetectable by design.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
+
+## Features
+
+- 🛡️ **C++ level anti-detection** — Camoufox patches Firefox at native level, not JS shims
+- 🔍 **14 search engines** — Google, Bing, DuckDuckGo, YouTube, GitHub, and more
+- 🕷️ **Recursive crawler** — Depth control, regex filters, delay, output to JSONL
+- 📸 **Screenshots & PDF** — Full page, viewport, custom resolution
+- 🧲 **Data extraction** — Links, images, meta, headings, CSS selectors
+- 🎭 **Browser profiles** — Persistent fingerprint identities with cookie storage
+- 🔄 **Proxy rotation** — Pool management with health checking
+- 🤖 **Human simulation** — Bezier mouse curves, natural typing, scroll patterns
+- 👻 **Daemon mode** — Background browser for instant command execution
+- 🧩 **MCP server** — Plug into Claude Desktop, Cursor, and other AI agents
+- 📦 **SDK mode** — Import as a library in your own Node.js projects
+
+## Install
+
+```bash
+git clone https://github.com/Youhai020616/stealth-cli.git
+cd stealth-cli
+npm install        # Installs deps + downloads Camoufox browser (~300MB)
+npm link           # Makes 'stealth' command available globally
+```
+
+## Quick Start
+
+```bash
+# Browse a page
+stealth browse https://example.com
+
+# Screenshot
+stealth screenshot https://example.com -o page.png
+
+# Search with anti-detection
+stealth search google "best coffee beans" -f json
+
+# Extract structured data
+stealth extract https://example.com --links --format json
+
+# Crawl a site
+stealth crawl https://example.com --depth 2 --limit 50 -o results.jsonl
+
+# Interactive REPL
+stealth interactive --url https://example.com
+```
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `stealth browse <url>` | Visit URL, print page content |
+| `stealth screenshot <url>` | Take a screenshot |
+| `stealth pdf <url>` | Save page as PDF |
+| `stealth search <engine> <query>` | Search the web |
+| `stealth extract <url>` | Extract structured data |
+| `stealth crawl <url>` | Recursive crawling |
+| `stealth interactive` | Interactive REPL |
+| `stealth batch <file>` | Batch process URLs from file |
+| `stealth monitor <url>` | Monitor page for changes |
+| `stealth fingerprint` | Show browser fingerprint info |
+
+### Management
+
+| Command | Description |
+|---------|-------------|
+| `stealth daemon start` | Start background browser |
+| `stealth daemon stop` | Stop background browser |
+| `stealth daemon status` | Show daemon status |
+| `stealth profile create <name>` | Create browser identity |
+| `stealth profile list` | List all profiles |
+| `stealth proxy add <url>` | Add proxy to pool |
+| `stealth proxy list` | List proxies |
+| `stealth proxy test` | Test proxy connectivity |
+| `stealth config set <key> <val>` | Set default config |
+| `stealth mcp` | Start MCP server for AI agents |
+
+---
+
+### `stealth browse <url>`
+
+```bash
+stealth browse https://example.com                      # Text content
+stealth browse https://example.com -f json              # JSON output
+stealth browse https://example.com -f snapshot           # Accessibility tree
+stealth browse https://example.com --proxy http://proxy:8080
+stealth browse https://example.com --cookies cookies.txt
+stealth browse https://example.com --profile us-desktop  # Use saved profile
+stealth browse https://example.com --humanize            # Human behavior
+```
+
+### `stealth screenshot <url>`
+
+```bash
+stealth screenshot https://example.com                   # → screenshot.png
+stealth screenshot https://example.com -o page.jpg       # JPEG output
+stealth screenshot https://example.com --full             # Full page
+stealth screenshot https://example.com --width 1920 --height 1080
+```
+
+### `stealth search <engine> <query>`
+
+**Supported engines:** google, bing, duckduckgo, youtube, github, stackoverflow, npmjs, amazon, reddit, wikipedia, twitter, linkedin, tiktok, yelp
+
+```bash
+stealth search google "web scraping tools" -f json
+stealth search github "camoufox" --max 20
+stealth search duckduckgo "privacy browser" -f markdown
+```
+
+### `stealth extract <url>`
+
+```bash
+stealth extract https://example.com --links              # All links
+stealth extract https://example.com --images             # All images
+stealth extract https://example.com --meta               # Meta & OG tags
+stealth extract https://example.com --headers            # h1-h6 headings
+stealth extract https://example.com -s ".price" --all    # CSS selector
+stealth extract https://example.com -s "a" -a "href"     # Attributes
+```
+
+### `stealth crawl <url>`
+
+```bash
+stealth crawl https://example.com -d 2 -l 50             # Depth 2, max 50
+stealth crawl https://example.com --delay 2000            # 2s between pages
+stealth crawl https://example.com --include "blog"        # URL regex filter
+stealth crawl https://example.com --exclude "login|admin"
+stealth crawl https://example.com -o results.jsonl        # Save to file
+```
+
+### `stealth interactive`
+
+Interactive REPL for manual browsing.
+
+```bash
+stealth interactive                                # Start empty
+stealth interactive --url https://example.com      # Start with a page
+stealth interactive --no-headless                  # Show browser window
+```
+
+REPL commands: `goto`, `search`, `click`, `type`, `snapshot`, `text`, `links`, `screenshot`, `back`, `forward`, `eval`, `help`, `exit`
+
+## Daemon Mode
+
+Keep a browser alive in the background for instant reuse. No cold start.
+
+```bash
+stealth daemon start                   # Start background browser
+stealth browse https://example.com     # ← Uses daemon automatically
+stealth daemon status                  # Check status
+stealth daemon stop                    # Shut down
+```
+
+The daemon auto-shuts down after 5 minutes of idle time.
+
+## Browser Profiles
+
+Create persistent browser identities with unique fingerprints, cookies, and proxy settings.
+
+```bash
+# Create from preset
+stealth profile create mybot --preset us-desktop
+stealth profile create jpbot --preset jp-desktop
+
+# Create with random fingerprint
+stealth profile create random1 --random
+
+# Use profile
+stealth browse https://example.com --profile mybot
+
+# Cookies are auto-saved between sessions
+stealth profile list
+```
+
+**Available presets:** `us-desktop`, `us-laptop`, `uk-desktop`, `de-desktop`, `jp-desktop`, `cn-desktop`, `mobile-ios`, `mobile-android`
+
+## Proxy Support
+
+```bash
+# Single proxy
+stealth browse https://example.com --proxy http://user:pass@host:port
+
+# Proxy pool rotation
+stealth proxy add http://proxy1:8080
+stealth proxy add http://proxy2:8080
+stealth proxy add socks5://proxy3:1080
+stealth browse https://example.com --proxy-rotate    # Auto-rotate
+
+# Test proxies
+stealth proxy test
+```
+
+When a proxy is used, Camoufox automatically matches locale, timezone, and geolocation to the proxy's exit IP via GeoIP.
+
+## MCP Server (AI Agent Integration)
+
+Use stealth-cli as a tool in Claude Desktop, Cursor, or any MCP-compatible AI agent.
+
+```bash
+stealth mcp    # Start MCP server (stdio)
+```
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stealth": {
+      "command": "node",
+      "args": ["/path/to/stealth-cli/bin/stealth.js", "mcp"]
+    }
+  }
+}
+```
+
+**Available MCP tools:** `stealth_browse`, `stealth_screenshot`, `stealth_search`, `stealth_extract`, `stealth_click`, `stealth_type`, `stealth_evaluate`
+
+## Pipe-Friendly
+
+stdout = data, stderr = status messages. Perfect for piping:
+
+```bash
+# Parse with jq
+stealth browse https://api.example.com -f json | jq '.title'
+
+# Chain commands
+stealth extract https://example.com --links -f json \
+  | jq '.[].url' \
+  | xargs -I {} stealth screenshot {} -o {}.png
+
+# Batch from file
+cat urls.txt | xargs -I {} stealth browse {} -f json > output.jsonl
+```
+
+## As a Library (SDK)
+
+```javascript
+import {
+  launchBrowser, closeBrowser, navigate,
+  getTextContent, takeScreenshot
+} from 'stealth-cli';
+
+const handle = await launchBrowser({
+  headless: true,
+  proxy: 'http://proxy:8080',
+  profile: 'us-desktop',
+  humanize: true,
+});
+
+await navigate(handle, 'https://example.com');
+const text = await getTextContent(handle);
+const screenshot = await takeScreenshot(handle, { path: 'page.png' });
+
+await closeBrowser(handle);
+```
+
+## How Anti-Detection Works
+
+stealth-cli uses [Camoufox](https://github.com/daijro/camoufox), a Firefox fork that patches fingerprint generation at the **C++ level**:
+
+| Fingerprint Vector | Approach |
+|---|---|
+| `navigator.hardwareConcurrency` | Spoofed in C++ |
+| WebGL renderer / vendor | Spoofed in C++ |
+| AudioContext fingerprint | Spoofed in C++ |
+| Canvas fingerprint | Spoofed in C++ |
+| Screen geometry | Spoofed in C++ |
+| WebRTC leak | Built-in protection |
+| TLS fingerprint | Firefox native (not Chromium) |
+
+**No JavaScript shims. No detectable wrappers.** The browser reports spoofed values natively.
+
+## Configuration
+
+```bash
+stealth config set headless false      # Show browser window by default
+stealth config set proxy http://p:8080 # Default proxy
+stealth config set humanize true       # Always simulate human behavior
+stealth config set format json         # Default output format
+stealth config set retries 3           # Default retry count
+```
+
+Config stored at `~/.stealth/config.json`.
+
+## License
+
+MIT

package/bin/stealth.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * stealth-cli — Anti-detection browser CLI powered by Camoufox
+ */
+
+import { program } from 'commander';
+import { registerBrowse } from '../src/commands/browse.js';
+import { registerScreenshot } from '../src/commands/screenshot.js';
+import { registerSearch } from '../src/commands/search.js';
+import { registerExtract } from '../src/commands/extract.js';
+import { registerCrawl } from '../src/commands/crawl.js';
+import { registerInteractive } from '../src/commands/interactive.js';
+import { registerDaemon } from '../src/commands/daemon.js';
+import { registerProfile } from '../src/commands/profile.js';
+import { registerProxy } from '../src/commands/proxy.js';
+import { registerPdf } from '../src/commands/pdf.js';
+import { registerMonitor } from '../src/commands/monitor.js';
+import { registerBatch } from '../src/commands/batch.js';
+import { registerFingerprint } from '../src/commands/fingerprint.js';
+import { registerServe } from '../src/commands/serve.js';
+import { registerMcp } from '../src/commands/mcp.js';
+import { registerConfig } from '../src/commands/config.js';
+
+program
+  .name('stealth')
+  .description('🦊 Anti-detection browser CLI powered by Camoufox')
+  .version('0.4.0');
+
+// Core commands
+registerBrowse(program);
+registerScreenshot(program);
+registerSearch(program);
+registerExtract(program);
+registerCrawl(program);
+registerInteractive(program);
+registerPdf(program);
+registerBatch(program);
+registerMonitor(program);
+registerFingerprint(program);
+registerServe(program);
+registerMcp(program);
+
+// Management commands
+registerDaemon(program);
+registerProfile(program);
+registerProxy(program);
+registerConfig(program);
+
+program.parse();

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "stealth-cli",
+  "version": "0.5.0",
+  "description": "Anti-detection browser CLI powered by Camoufox. Browse, search, scrape, and crawl the web with C++ level fingerprint spoofing.",
+  "type": "module",
+  "bin": {
+    "stealth": "bin/stealth.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/stealth.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:e2e": "vitest run tests/e2e",
+    "postinstall": "npx camoufox-js fetch || true",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "browser",
+    "cli",
+    "anti-detection",
+    "camoufox",
+    "stealth",
+    "scraping",
+    "automation",
+    "headless",
+    "fingerprint",
+    "web-scraping",
+    "anti-bot",
+    "cloudflare",
+    "playwright",
+    "firefox"
+  ],
+  "author": "xyh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "",
+  "bugs": {
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "camoufox-js": "^0.9.2",
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "ora": "^8.0.0",
+    "playwright-core": "^1.58.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,244 @@
+# stealth-cli
+
+Anti-detection browser CLI powered by Camoufox. Browse the web, search, extract data, take screenshots, and crawl pages — all with C++ level fingerprint spoofing that bypasses Cloudflare, Google, and most bot detection systems.
+
+## When to use
+
+- User needs to browse a website that blocks automated tools
+- User needs to scrape data from protected pages
+- User needs to search Google/Bing/DuckDuckGo without being blocked
+- User needs screenshots of pages behind anti-bot protection
+- User needs to monitor a page for changes
+- User needs to extract structured data (links, images, meta tags)
+- User needs to crawl a site with anti-detection
+
+## Prerequisites
+
+```bash
+cd ~/Desktop/stealth-cli
+npm install    # installs deps + downloads Camoufox (~300MB first time)
+```
+
+## Commands
+
+### Browse a page
+
+```bash
+# Text output (default)
+stealth browse https://example.com
+
+# JSON output with metadata
+stealth browse https://example.com -f json
+
+# With proxy
+stealth browse https://example.com --proxy http://user:pass@host:port
+
+# With saved profile identity
+stealth browse https://example.com --profile us-desktop
+```
+
+### Screenshot
+
+```bash
+stealth screenshot https://example.com -o page.png
+stealth screenshot https://example.com --full -o full.png    # full page
+stealth screenshot https://example.com --width 1920 --height 1080
+```
+
+### Search (bypasses anti-bot)
+
+```bash
+# Google (auto-humanized: visits homepage, types query, presses enter)
+stealth search google "web scraping tools" -f json
+
+# Other engines
+stealth search duckduckgo "query" -f json
+stealth search bing "query" -f json
+stealth search youtube "query" -f json
+stealth search github "query" -f json
+
+# With warmup (visit random site first to build browsing history)
+stealth search google "query" -f json --warmup
+
+# Supported: google, duckduckgo, bing, youtube, github, amazon,
+#   reddit, wikipedia, twitter, linkedin, tiktok, stackoverflow,
+#   npmjs, yelp
+```
+
+### Extract data
+
+```bash
+# Extract all links
+stealth extract https://example.com --links
+
+# Extract meta tags (title, description, og:*)
+stealth extract https://example.com --meta
+
+# Extract all headings
+stealth extract https://example.com --headers
+
+# Extract by CSS selector
+stealth extract https://example.com -s ".product-title" --all
+
+# Extract image URLs
+stealth extract https://example.com --images
+```
+
+### Crawl
+
+```bash
+# Crawl 2 levels deep, max 20 pages
+stealth crawl https://example.com -d 2 -l 20
+
+# Save to file
+stealth crawl https://example.com -o results.jsonl
+
+# Filter URLs
+stealth crawl https://example.com --include "blog" --exclude "login"
+
+# With delay between pages
+stealth crawl https://example.com --delay 2000
+```
+
+### Monitor for changes
+
+```bash
+# Watch for any change (check every 60s)
+stealth monitor https://example.com/price -s ".price" -i 60
+
+# Alert when text appears
+stealth monitor https://example.com --contains "In Stock"
+
+# Alert when text disappears
+stealth monitor https://example.com --not-contains "Sold Out"
+
+# JSON output for piping
+stealth monitor https://example.com --json -n 10
+```
+
+### Batch processing
+
+```bash
+# Create a URL list file
+echo "https://example.com\nhttps://httpbin.org/ip" > urls.txt
+
+# Browse all URLs
+stealth batch urls.txt -c browse --skip-errors
+
+# Screenshot all URLs
+stealth batch urls.txt -c screenshot -o ./screenshots/
+```
+
+### Browser fingerprint check
+
+```bash
+# Show current fingerprint
+stealth fingerprint
+
+# Run anti-detection tests
+stealth fingerprint --check
+
+# Compare fingerprints across multiple launches
+stealth fingerprint --compare 3
+```
+
+### Profile management (persistent identities)
+
+```bash
+# Create from preset
+stealth profile create work --preset us-desktop
+stealth profile create jp --preset jp-desktop
+
+# Create random
+stealth profile create random1 --random
+
+# List profiles
+stealth profile list
+
+# Use profile (auto-saves cookies on exit)
+stealth browse https://example.com --profile work
+
+# Available presets: us-desktop, us-laptop, uk-desktop, de-desktop,
+#   jp-desktop, cn-desktop, mobile-ios, mobile-android
+```
+
+### Session persistence
+
+```bash
+# Save/restore browsing session (cookies + last URL)
+stealth browse https://example.com --session my-task
+
+# Next time: auto-restores cookies and navigates to last URL
+stealth browse https://other.com --session my-task
+```
+
+### Proxy pool
+
+```bash
+stealth proxy add http://user:pass@host:port --label us-east
+stealth proxy list
+stealth proxy test          # test all proxies
+
+# Auto-rotate through pool
+stealth browse https://example.com --proxy-rotate
+stealth crawl https://example.com --proxy-rotate
+```
+
+### Daemon mode (fast startup)
+
+```bash
+stealth daemon start        # launch background browser
+stealth browse https://...  # instant (~1s vs ~6s cold start)
+stealth daemon status
+stealth daemon stop
+```
+
+### HTTP API server
+
+```bash
+stealth serve --port 9377
+
+# Then call via HTTP:
+curl -X POST http://localhost:9377/tabs -d '{"url":"https://example.com"}'
+curl http://localhost:9377/tabs/tab-1/text
+curl http://localhost:9377/tabs/tab-1/screenshot
+```
+
+### Interactive REPL
+
+```bash
+stealth interactive --url https://example.com
+
+# Commands: goto, search, click, hclick, type, htype, scroll,
+#   snapshot, text, title, url, links, screenshot, back, forward,
+#   reload, eval, wait, help, exit
+```
+
+## Output format
+
+All commands support `--format` or `-f`:
+- `text` — human-readable (default)
+- `json` — structured JSON
+- `jsonl` — one JSON object per line
+- `snapshot` — accessibility tree snapshot
+- `markdown` — markdown formatted
+
+stdout contains data, stderr contains status messages. Pipe-friendly:
+
+```bash
+stealth search google "query" -f json | jq '.results[].url'
+stealth extract https://example.com --links -f json | jq '.[].url'
+```
+
+## Common options (all commands)
+
+| Option | Description |
+|--------|-------------|
+| `--proxy <url>` | Use proxy server |
+| `--proxy-rotate` | Rotate through proxy pool |
+| `--profile <name>` | Use saved browser profile |
+| `--session <name>` | Persist/restore session |
+| `--cookies <file>` | Import Netscape cookie file |
+| `--humanize` | Enable human behavior simulation |
+| `--retries <n>` | Max retries on failure |
+| `--no-headless` | Show browser window |