screenshot-x402-cli

screenshot-x402 is the product: pay-per-request screenshots (and optional vision) for AI agents, with real browser rendering, MCP over Streamable HTTP, and x402 settlement in USDC—no caller API keys. The marketing site, discovery JSON, docs, and pricing all live there.

This repo is the official Node.js CLI for that service: it connects to the same MCP endpoint agents use, calls health (free) or paid tools (take_screenshot, analyze_screenshot) with withX402Client and viem, and writes PNG/JPEG, JSON, and an HTML report under your chosen output directory.

Default MCP URL: https://screenshotx402.com/mcp
Override with --mcp-url or MCP_URL (for example http://127.0.0.1:8787/mcp when developing the worker locally).

Requirements

• Node.js 20+
• Paid commands: a funded EVM wallet with USDC on the same network the server expects (default: base). Set X402_PRIVATE_KEY (never commit this).

Install

npm install -g screenshot-x402-cli

Or run without installing:

npx screenshot-x402-cli --help

Commands

After a global install, two equivalent binaries are available: screenshot-x402 and screenshot-x402-cli. Examples below use screenshot-x402.

| Command | Wallet | Description | | ------------ | ------ | ------------------------------------------------------------ | | health | No | Calls the free health tool. | | screenshot | Yes | Calls take_screenshot (~$0.01). | | analyze | Yes | Calls analyze_screenshot (~$0.03) plus server-side vision. | | list-tools | No | Prints MCP tool definitions as JSON. |

Free: health

screenshot-x402 health

Paid: screenshot or analyze

export X402_PRIVATE_KEY=0x...   # funded key — never commit
screenshot-x402 screenshot --page https://example.com
screenshot-x402 analyze --page https://example.com

CLI options

Global

| Option | Description | | ----------------- | ------------------------------------------------------------------------------------------------------ | | --mcp-url <url> | MCP Streamable HTTP URL (default: https://screenshotx402.com/mcp) | | --page <url> | Target URL (required for screenshot and analyze) | | --out <dir> | Output directory (default: ./output in the current working directory) | | --json | Print one JSON object on stdout (health, screenshot, analyze, list-tools); logs stay on stderr | | -h, --help | Show usage |

Common to screenshot and analyze

| Flag | Description | | ----------------------------- | --------------------------------------------------- | | --width <px> | Viewport width (default: 1280) | | --height <px> | Viewport height (default: 720) | | --full-page | Capture the full scrollable page | | --color-scheme <light\|dark> | Color scheme | | --device-scale-factor <1-3> | Pixel ratio / sharpness (default: 1) | | --hide <selector> | Repeat for each CSS selector to hide before capture |

screenshot only

| Flag | Description | | ------------------- | --------------------------------------------------- | | --format <png\|jpeg> | Output format | | --delay <ms> | Extra wait after load (default: 0) | | --cache-ttl <sec> | Cache TTL; 0 skips cache reads (default: 86400) |

analyze only

| Flag | Description | | ----------------- | ------------------------------------------- | | --prompt <text> | Vision instruction (default: short summary) |

Examples

# Dark mode + HiDPI + hide overlays
screenshot-x402 screenshot --page https://example.com \
  --color-scheme dark \
  --device-scale-factor 2 \
  --hide "#cookie-consent" \
  --hide ".sticky-promo"

# Full-page JPEG, custom viewport, delay
screenshot-x402 screenshot --page https://example.com \
  --full-page --format jpeg --width 1920 --height 1080 --delay 1500

# Vision with the same render options as screenshot
screenshot-x402 analyze --page https://example.com \
  --color-scheme dark \
  --device-scale-factor 2 \
  --prompt "List all visible headings."

Environment variables

| Variable | Description | | ------------------ | ---------------------------------------------- | | X402_PRIVATE_KEY | 0x… — required for paid tools | | X402_NETWORK | EVM network id (default: base) | | MCP_URL | Default MCP endpoint if --mcp-url is omitted | | OUT_DIR | Default output directory if --out is omitted |

Output

Each run creates timestamped files under your output directory (default ./output; add output/ to .gitignore in your project if needed):

| File | Purpose | | ----------------- | ----------------------------------------------------------------- | | *.html | Open in a browser — embeds images as data: URLs and text blocks | | *.png / *.jpg | Decoded screenshot bytes when the tool returns an image | | *.json | Raw tool result for debugging |

With --json, the CLI also prints a single line of JSON on stdout with command, pageUrl, isError, text (tool text parts), absolute paths to the files above, and _meta. Image base64 is not repeated on stdout (use the saved *.json or image files).

Develop from this repo

cd screenshot-x402-cli
npm install
npm run build
node dist/index.js --help
# or during development:
npm start -- health

Publish to npm

From screenshot-x402-cli/:

npm run build
npm publish --access public

prepublishOnly runs npm run build automatically. Ensure you are logged in (npm login) and the package name screenshot-x402-cli is available on your scope/account.

Safety

• Treat X402_PRIVATE_KEY like a production secret; use limited fund wallet for experiments.
• This CLI auto-approves x402 payments in code for automation — not suitable for unattended use with high-value or mainnet wallets without your own safeguards.

License

MIT — see LICENSE.