stealth-cli 0.5.0 → 0.5.1

package/README.md

@@ -1,186 +1,250 @@
-# 🦊 stealth-cli
+<div align="center">
+  <h1>🦊 stealth-cli</h1>
+  <p><strong>Anti-detection browser CLI powered by Camoufox</strong></p>
+  <p>Browse, search, scrape, and crawl the web with C++ level fingerprint spoofing.<br/>Bypasses Cloudflare, Google, and most bot detection systems.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/stealth-cli"><img src="https://img.shields.io/npm/v/stealth-cli?color=blue" alt="npm version" /></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a>
+    <a href="https://camoufox.com"><img src="https://img.shields.io/badge/engine-Camoufox-red" alt="Camoufox" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D18-green" alt="Node" />
+    <img src="https://img.shields.io/badge/tests-59%20passing-brightgreen" alt="Tests" />
+  </p>
+</div>
 
-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.
+---
+
+## Why
 
-[![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)
+Headless Chrome gets fingerprinted. Playwright gets blocked. Stealth plugins become the fingerprint.
 
-## Features
+**stealth-cli** uses [Camoufox](https://camoufox.com) — a Firefox fork that patches fingerprint generation at the **C++ implementation level**. No JavaScript shims, no wrappers, no tells. The browser reports spoofed values natively.
 
-- 🛡️ **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
+Wrap that in a developer-friendly CLI with 16 commands, and you get a tool that both humans and AI agents can use.
 
 ## Install
 
 ```bash
-git clone https://github.com/Youhai020616/stealth-cli.git
+# From npm (recommended)
+npm install -g stealth-cli
+
+# From source
+git clone https://github.com/user/stealth-cli.git
 cd stealth-cli
 npm install        # Installs deps + downloads Camoufox browser (~300MB)
-npm link           # Makes 'stealth' command available globally
+npm link           # Makes 'stealth' command globally available
 ```
 
+> First run downloads the Camoufox browser binary (~300MB). Subsequent runs are instant.
+
 ## Quick Start
 
 ```bash
-# Browse a page
+# Browse a page with anti-detection
 stealth browse https://example.com
 
-# Screenshot
+# Take a screenshot
 stealth screenshot https://example.com -o page.png
 
-# Search with anti-detection
+# Search Google without getting blocked
 stealth search google "best coffee beans" -f json
 
-# Extract structured data
-stealth extract https://example.com --links --format json
+# Extract all links from a page
+stealth extract https://example.com --links
 
 # Crawl a site
 stealth crawl https://example.com --depth 2 --limit 50 -o results.jsonl
 
-# Interactive REPL
+# Interactive browsing (REPL)
 stealth interactive --url https://example.com
 ```
 
 ## Commands
 
-### Core
+### Core (11 commands)
 
 | 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
+| `stealth browse <url>` | Visit URL, print page content (text/json/snapshot) |
+| `stealth screenshot <url>` | Take a screenshot (PNG/JPEG, full page, custom size) |
+| `stealth search <engine> <query>` | Search with anti-detection (14 engines) |
+| `stealth extract <url>` | Extract links, images, meta, headings, CSS selectors |
+| `stealth crawl <url>` | Recursive crawling with depth/filter/delay control |
+| `stealth interactive` | Interactive REPL with 20+ browsing commands |
+| `stealth pdf <url>` | Save page as PDF / full-page screenshot |
+| `stealth batch <file>` | Batch process URLs from a file |
+| `stealth monitor <url>` | Watch a page for changes (price drops, stock alerts) |
+| `stealth fingerprint` | Check browser fingerprint & anti-detection status |
+| `stealth serve` | Start HTTP API server for external integrations |
+
+### Management (5 commands)
 
 | 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 daemon start/stop/status` | Background browser for instant startup (~1s vs ~6s) |
+| `stealth profile create/list/delete` | Persistent browser identities (8 presets + random) |
+| `stealth proxy add/list/test` | Proxy pool with rotation and health checking |
+| `stealth config set/get/list/reset` | Global defaults (~/.stealth/config.json) |
+| `stealth mcp` | MCP server for Claude Desktop / Cursor |
 
 ---
 
-### `stealth browse <url>`
+## Usage
+
+### Browse
 
 ```bash
-stealth browse https://example.com                      # Text content
-stealth browse https://example.com -f json              # JSON output
+stealth browse https://example.com                      # Text output
+stealth browse https://example.com -f json              # JSON with metadata
 stealth browse https://example.com -f snapshot           # Accessibility tree
+stealth browse https://example.com --humanize            # Human behavior simulation
+stealth browse https://example.com --profile us-desktop  # Use saved identity
 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>`
+### Screenshot
 
 ```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 -o page.png
+stealth screenshot https://example.com --full            # Full page
 stealth screenshot https://example.com --width 1920 --height 1080
 ```
 
-### `stealth search <engine> <query>`
+### Search
 
-**Supported engines:** google, bing, duckduckgo, youtube, github, stackoverflow, npmjs, amazon, reddit, wikipedia, twitter, linkedin, tiktok, yelp
+14 supported engines with structured result extraction.
+
+Google uses a special anti-detection flow: visits homepage → types query → presses Enter (not direct URL).
 
 ```bash
-stealth search google "web scraping tools" -f json
-stealth search github "camoufox" --max 20
-stealth search duckduckgo "privacy browser" -f markdown
+stealth search google "web scraping tools" -f json       # Auto-humanized
+stealth search google "query" -f json --warmup           # Extra: visit random site first
+stealth search duckduckgo "privacy browser" -f json
+stealth search bing "anti-detect browser" -f json
+stealth search youtube "tutorial" -f json                # Video metadata
+stealth search github "camoufox" -f json                 # Repo results
+stealth search amazon "mechanical keyboard" -f json
 ```
 
-### `stealth extract <url>`
+**All 14 engines:** google, bing, duckduckgo, youtube, github, amazon, reddit, wikipedia, twitter, linkedin, tiktok, stackoverflow, npmjs, yelp
+
+### Extract
 
 ```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 --meta               # Title, description, 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 extract https://example.com -s "a" -a "href" --all  # Attributes
 ```
 
-### `stealth crawl <url>`
+### Crawl
 
 ```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 -d 2 -l 50             # Depth 2, max 50 pages
+stealth crawl https://example.com -o results.jsonl        # Save to file
 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 crawl https://example.com --delay 2000 --humanize # Human-like crawling
+stealth crawl https://example.com --proxy-rotate          # Rotate through proxy pool
+```
+
+### Monitor
+
+Watch pages for changes — ideal for price tracking, stock alerts, content monitoring.
+
+```bash
+stealth monitor https://shop.com/item -s ".price" -i 60  # Check price every 60s
+stealth monitor https://shop.com/item --contains "In Stock"
+stealth monitor https://example.com --not-contains "Sold Out"
+stealth monitor https://example.com --json -n 10          # JSON output, 10 checks max
 ```
 
-### `stealth interactive`
+### Batch
 
-Interactive REPL for manual browsing.
+```bash
+echo "https://example.com
+https://github.com
+https://httpbin.org/ip" > urls.txt
+
+stealth batch urls.txt -c browse --skip-errors            # Browse all
+stealth batch urls.txt -c screenshot -o ./screenshots/    # Screenshot all
+stealth batch urls.txt -c extract -s "h1"                 # Extract from all
+```
+
+### Fingerprint
 
 ```bash
-stealth interactive                                # Start empty
-stealth interactive --url https://example.com      # Start with a page
-stealth interactive --no-headless                  # Show browser window
+stealth fingerprint                   # Show current browser fingerprint
+stealth fingerprint --check           # Run anti-detection tests (CreepJS, WebDriver)
+stealth fingerprint --compare 3       # Launch 3 times, compare if fingerprints vary
+stealth fingerprint --profile jp-desktop --json
 ```
 
-REPL commands: `goto`, `search`, `click`, `type`, `snapshot`, `text`, `links`, `screenshot`, `back`, `forward`, `eval`, `help`, `exit`
+### Interactive REPL
+
+```bash
+stealth interactive --url https://example.com
+
+stealth> goto https://google.com
+stealth> search duckduckgo hello world
+stealth> click "button.submit"
+stealth> hclick "a.link"              # Human-like click (mouse movement)
+stealth> type "input[name=q]" hello
+stealth> htype "input[name=q]" hello  # Human-like typing (variable speed)
+stealth> scroll down 3
+stealth> text                         # Page text
+stealth> snapshot                     # Accessibility tree
+stealth> links                        # All links
+stealth> screenshot page.png
+stealth> eval document.title          # Run JavaScript
+stealth> back / forward / reload
+stealth> exit
+```
+
+---
 
 ## Daemon Mode
 
-Keep a browser alive in the background for instant reuse. No cold start.
+Keep a browser alive in the background. Commands reuse it instantly.
 
 ```bash
 stealth daemon start                   # Start background browser
-stealth browse https://example.com     # ← Uses daemon automatically
+stealth browse https://example.com     # ~1.2s (vs ~6s cold start)
+stealth browse https://other.com       # ~1.2s
 stealth daemon status                  # Check status
-stealth daemon stop                    # Shut down
+stealth daemon stop                    # Shut down (auto-stops after 5min idle)
 ```
 
-The daemon auto-shuts down after 5 minutes of idle time.
-
 ## Browser Profiles
 
-Create persistent browser identities with unique fingerprints, cookies, and proxy settings.
+Persistent browser identities with unique fingerprints. Cookies auto-save between sessions.
 
 ```bash
-# Create from preset
-stealth profile create mybot --preset us-desktop
-stealth profile create jpbot --preset jp-desktop
+stealth profile create work --preset us-desktop
+stealth profile create japan --preset jp-desktop
+stealth profile create rand1 --random               # Random fingerprint
+stealth profile list
+stealth profile presets                              # Show all 8 presets
 
-# Create with random fingerprint
-stealth profile create random1 --random
+# Use profile — fingerprint + cookies auto-applied
+stealth browse https://example.com --profile work
+# → User-Agent: Windows, locale: en-US, timezone: America/New_York
+```
 
-# Use profile
-stealth browse https://example.com --profile mybot
+**Presets:** `us-desktop` · `us-laptop` · `uk-desktop` · `de-desktop` · `jp-desktop` · `cn-desktop` · `mobile-ios` · `mobile-android`
 
-# Cookies are auto-saved between sessions
-stealth profile list
-```
+## Session Persistence
+
+Save and restore browsing sessions (cookies + last URL + history).
+
+```bash
+stealth browse https://example.com --session my-task --profile work
+# → Cookies saved, URL remembered
 
-**Available presets:** `us-desktop`, `us-laptop`, `uk-desktop`, `de-desktop`, `jp-desktop`, `cn-desktop`, `mobile-ios`, `mobile-android`
+# Later: auto-restores cookies and navigates to last URL
+stealth browse https://other.com --session my-task
+```
 
 ## Proxy Support
 
@@ -188,87 +252,93 @@ stealth profile list
 # 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
+# Proxy pool with rotation
+stealth proxy add http://proxy1:8080 --label us --region US
+stealth proxy add http://proxy2:8080 --label eu --region EU
+stealth proxy test                                   # Test all proxies
+stealth proxy list                                   # List with status
 stealth browse https://example.com --proxy-rotate    # Auto-rotate
-
-# Test proxies
-stealth proxy test
+stealth crawl https://example.com --proxy-rotate     # Rotate per page
 ```
 
-When a proxy is used, Camoufox automatically matches locale, timezone, and geolocation to the proxy's exit IP via GeoIP.
+GeoIP: When using a proxy, Camoufox auto-matches locale, timezone, and geolocation to the proxy's exit IP.
 
-## MCP Server (AI Agent Integration)
+## Pipe-Friendly
 
-Use stealth-cli as a tool in Claude Desktop, Cursor, or any MCP-compatible AI agent.
+stdout = data, stderr = status. Perfect for Unix pipes:
 
 ```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"]
-    }
-  }
-}
+stealth browse https://api.example.com -f json | jq '.title'
+stealth search google "query" -f json | jq '.results[].url'
+stealth extract https://example.com --links -f json | jq '.data[].url'
+stealth crawl https://example.com -o - | wc -l
 ```
 
-**Available MCP tools:** `stealth_browse`, `stealth_screenshot`, `stealth_search`, `stealth_extract`, `stealth_click`, `stealth_type`, `stealth_evaluate`
+## HTTP API Server
 
-## Pipe-Friendly
+```bash
+stealth serve --port 9377
 
-stdout = data, stderr = status messages. Perfect for piping:
+# Create tab + browse
+curl -X POST localhost:9377/tabs -H 'Content-Type: application/json' \
+  -d '{"url":"https://example.com"}'
 
-```bash
-# Parse with jq
-stealth browse https://api.example.com -f json | jq '.title'
+# Get page text
+curl localhost:9377/tabs/tab-1/text
 
-# Chain commands
-stealth extract https://example.com --links -f json \
-  | jq '.[].url' \
-  | xargs -I {} stealth screenshot {} -o {}.png
+# Screenshot (base64)
+curl localhost:9377/tabs/tab-1/screenshot
 
-# Batch from file
-cat urls.txt | xargs -I {} stealth browse {} -f json > output.jsonl
+# All endpoints: /health, /tabs, /tabs/:id/navigate, /tabs/:id/snapshot,
+#   /tabs/:id/text, /tabs/:id/screenshot, /tabs/:id/click, /tabs/:id/type,
+#   /tabs/:id/evaluate, /tabs/:id/close, /shutdown
 ```
 
 ## As a Library (SDK)
 
 ```javascript
-import {
-  launchBrowser, closeBrowser, navigate,
-  getTextContent, takeScreenshot
-} from 'stealth-cli';
+import { launchBrowser, closeBrowser, navigate, getTextContent } 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' });
+console.log(text);
 
 await closeBrowser(handle);
 ```
 
+## Configuration
+
+Set global defaults so you don't repeat flags:
+
+```bash
+stealth config set locale zh-CN          # Default Chinese locale
+stealth config set humanize true         # Always simulate human behavior
+stealth config set retries 3             # Default 3 retries
+stealth config set format json           # Default JSON output
+stealth config list                      # Show all settings
+stealth config reset                     # Reset to defaults
+```
+
+Stored at `~/.stealth/config.json`.
+
 ## How Anti-Detection Works
 
-stealth-cli uses [Camoufox](https://github.com/daijro/camoufox), a Firefox fork that patches fingerprint generation at the **C++ level**:
+```
+stealth-cli
+  └── camoufox-js (npm)
+       └── Camoufox (C++ Firefox fork)
+            └── Fingerprint spoofing at the native level
+```
 
 | Fingerprint Vector | Approach |
 |---|---|
 | `navigator.hardwareConcurrency` | Spoofed in C++ |
+| `navigator.webdriver` | Always `false` |
 | WebGL renderer / vendor | Spoofed in C++ |
 | AudioContext fingerprint | Spoofed in C++ |
 | Canvas fingerprint | Spoofed in C++ |
@@ -276,19 +346,37 @@ stealth-cli uses [Camoufox](https://github.com/daijro/camoufox), a Firefox fork
 | WebRTC leak | Built-in protection |
 | TLS fingerprint | Firefox native (not Chromium) |
 
-**No JavaScript shims. No detectable wrappers.** The browser reports spoofed values natively.
+No JavaScript shims. No detectable wrappers. The browser reports spoofed values natively.
 
-## Configuration
+## Common Options
 
-```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
-```
+Available on all core commands:
+
+| Option | Description |
+|--------|-------------|
+| `--proxy <url>` | Use proxy server |
+| `--proxy-rotate` | Rotate through proxy pool |
+| `--profile <name>` | Use saved browser identity |
+| `--session <name>` | Persist/restore browsing session |
+| `--cookies <file>` | Import Netscape-format cookie file |
+| `--humanize` | Simulate human behavior |
+| `--retries <n>` | Max retries on failure (default: 2) |
+| `--no-headless` | Show browser window |
+| `-f, --format` | Output format: text, json, jsonl, snapshot, markdown |
 
-Config stored at `~/.stealth/config.json`.
+## Project Stats
+
+```
+Version:     0.5.0
+Commands:    16
+Tests:       59 passing
+Source:      5,700+ lines
+Files:       44
+Extractors:  6 (Google, Bing, DuckDuckGo, YouTube, GitHub, generic)
+Presets:     8 browser profiles
+Engine:      Camoufox (C++ Firefox fork)
+License:     MIT
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stealth-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Anti-detection browser CLI powered by Camoufox. Browse, search, scrape, and crawl the web with C++ level fingerprint spoofing.",
   "type": "module",
   "bin": {