capsolver-cli

CLI tool for the CapSolver captcha solving API. Solve reCAPTCHA, Turnstile, GeeTest, image captchas, and more from your terminal.

Compiles to a single standalone binary via bun build --compile.

Setup

bun install
cp .env.example .env
# Add your API key to .env:
# CAPSOLVER_API_KEY=CAP-xxxxx

Get your API key from dashboard.capsolver.com.

Quick Start

# Check balance
capsolver

# Solve an image captcha
capsolver solve image captcha.png

# Solve reCAPTCHA v2
capsolver solve recaptcha-v2 --url https://example.com --key 6Le-wvkSAAAAAPBMRTvw0Q4Muexq

# Solve Cloudflare Turnstile
capsolver solve turnstile --url https://example.com --key 0x4AAAAAAA

# Get raw JSON output
capsolver solve recaptcha-v2 --url https://example.com --key SITEKEY --json

# Get just the token (for piping)
capsolver solve turnstile --url https://example.com --key SITEKEY --quiet

Commands

capsolver (no args)

Shows account balance. Same as capsolver balance.

capsolver balance

Balance: $25.50

Packages:
  reCAPTCHA v2 500K                500000 calls  active  expires 12/18/2024

capsolver solve <type>

Solve a captcha. Creates the task, auto-polls for the result, and prints the solution.

solve image <file>

OCR / image-to-text. Returns the result immediately (synchronous).

capsolver solve image captcha.png
capsolver solve image screenshot.jpg --module number
cat captcha.png | capsolver solve image -    # Read from stdin

| Flag | Description | |---|---| | --module <module> | common (default) or number (digits only) | | --url <url> | Page source URL to improve accuracy |

solve recaptcha-v2

capsolver solve recaptcha-v2 --url https://example.com --key 6Le-wvkSAAAA...
capsolver solve recaptcha-v2 --url https://example.com --key SITEKEY --enterprise
capsolver solve recaptcha-v2 --url https://example.com --key SITEKEY --invisible
capsolver solve recaptcha-v2 --url https://example.com --key SITEKEY --proxy 1.2.3.4:8080:user:pass

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --key <sitekey> | Yes | reCAPTCHA site key | | --enterprise | No | Use enterprise task type | | --invisible | No | Invisible reCAPTCHA (no checkbox) | | --proxy <proxy> | No | Use your own proxy (switches from ProxyLess) | | --page-action <action> | No | The sa parameter from /anchor | | --data-s <value> | No | The s parameter from /anchor | | --api-domain <domain> | No | google.com or recaptcha.net |

solve recaptcha-v3

capsolver solve recaptcha-v3 --url https://example.com --key SITEKEY
capsolver solve recaptcha-v3 --url https://example.com --key SITEKEY --action login --min-score 0.7

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --key <sitekey> | Yes | reCAPTCHA site key | | --action <action> | No | Page action value | | --min-score <score> | No | Minimum score (0.1-0.9) | | --enterprise | No | Use enterprise task type | | --proxy <proxy> | No | Use your own proxy | | --api-domain <domain> | No | google.com or recaptcha.net |

solve turnstile

capsolver solve turnstile --url https://example.com --key 0x4AAAAAAA
capsolver solve turnstile --url https://example.com --key KEY --action login --cdata session-id

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --key <sitekey> | Yes | Turnstile site key | | --action <action> | No | data-action attribute value | | --cdata <cdata> | No | data-cdata attribute value |

solve geetest

Supports both v3 and v4. Provide --gt + --challenge for v3, or --captcha-id for v4.

# GeeTest v3
capsolver solve geetest --url https://example.com --gt GT_VALUE --challenge CHALLENGE_VALUE

# GeeTest v4
capsolver solve geetest --url https://example.com --captcha-id CAPTCHA_ID

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --gt <gt> | v3 only | GeeTest gt parameter | | --challenge <challenge> | v3 only | GeeTest challenge parameter | | --captcha-id <id> | v4 only | GeeTest v4 captchaId | | --subdomain <sub> | No | GeeTest API server subdomain |

solve datadome

capsolver solve datadome --url https://example.com --captcha-url https://geo.captcha-delivery.com/...

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --captcha-url <url> | Yes | DataDome captcha URL | | --proxy <proxy> | No | Proxy string |

solve aws-waf

capsolver solve aws-waf --url https://example.com
capsolver solve aws-waf --url https://example.com --proxy 1.2.3.4:8080

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --proxy <proxy> | No | Proxy string (switches from ProxyLess) |

solve mtcaptcha

capsolver solve mtcaptcha --url https://example.com --key SITEKEY

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --key <sitekey> | Yes | MTCaptcha site key |

solve cloudflare-challenge

capsolver solve cloudflare-challenge --url https://example.com

| Flag | Required | Description | |---|---|---| | --url <url> | Yes | Target page URL | | --proxy <proxy> | No | Proxy string |

capsolver task <taskId>

Check the status or retrieve the result of an existing task.

capsolver task 37223a89-06ed-442c-a0b8-22067b79c5b4
capsolver task 37223a89 --json

capsolver config

Show or update configuration.

capsolver config                          # Show current config (masked key)
capsolver config set-key CAP-xxxxx        # Save API key to .env

Global Flags

| Flag | Description | |---|---| | --json | Output raw JSON (for scripting/piping) | | --quiet | Output only the solution value (token, text, etc.) | | --timeout <seconds> | Polling timeout, default 120s | | --version | Show version | | --help | Show help |

Output Modes

Default — Pretty-printed with colors and a spinner while polling:

Task: 37223a89-06ed-442c-a0b8-22067b79c5b4
Status: ready
Solution:
  gRecaptchaResponse: 03AGdBq25SxXT-pmS...
  userAgent: Mozilla/5.0...

--json — Raw JSON, no colors, no spinner:

{
  "errorId": 0,
  "taskId": "37223a89-06ed-442c-a0b8-22067b79c5b4",
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq25SxXT-pmS..."
  }
}

--quiet — Just the token/text value, nothing else. Best for piping:

TOKEN=$(capsolver solve recaptcha-v2 --url ... --key ... --quiet)
curl -d "g-recaptcha-response=$TOKEN" https://example.com/submit

Environment

| Variable | Description | |---|---| | CAPSOLVER_API_KEY | Your CapSolver API key (required) |

Bun auto-loads .env from the working directory.

Development

bun run dev -- balance                     # Run in dev mode
bun run dev -- solve image captcha.png
bun test                                   # Run all tests
bun test test/unit                         # Unit tests only
bun test test/integration                  # Integration tests only

Building

bun run build    # Produces ./capsolver binary

The binary is standalone — no Bun or Node required to run it.