Metadata-Version: 2.4
Name: captchaflow-cli
Version: 0.1.0
Summary: CLI for the CaptchaFlow captcha-solving API (captcha.dataleads.pro)
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8
Requires-Dist: httpx>=0.27

# captchaflow-cli

Command-line client for the [CaptchaFlow](https://captcha.dataleads.pro) captcha-solving API.

Solves reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and image captchas from your terminal.

## Install

```bash
cd captchaflow-cli
pip install -e .
```

Installs the `captchaflow` command into your environment (requires Python 3.9+).

## Configuration

The API key is resolved in this order:

1. `--key` flag on any command
2. `CAPTCHAFLOW_KEY` environment variable

If neither is set, the CLI exits with instructions. The optional `CAPTCHAFLOW_BASE_URL`-style override is available as a top-level `--base-url` flag (default `https://captcha.dataleads.pro/v1`).

```bash
export CAPTCHAFLOW_KEY=your_client_key
```

## Commands

| Command | Purpose |
|---|---|
| `captchaflow health` | Check API health (no auth) |
| `captchaflow balance` | Show account balance |
| `captchaflow solve-image <image_path>` | Solve an image captcha (OCR) |
| `captchaflow recaptcha <website_url> <site_key>` | Solve reCAPTCHA v2 (or `--v3`) |
| `captchaflow hcaptcha <website_url> <site_key>` | Solve hCaptcha |
| `captchaflow turnstile <website_url> <site_key>` | Solve Cloudflare Turnstile |

All data commands accept `--json` for raw JSON output. Global flags `--base-url` and `--key` go **before** the subcommand.

## Examples

### health

```bash
captchaflow health
# {
#   "status": "ok",
#   "version": "1.0.0"
# }
```

### balance

```bash
captchaflow balance
# 12.5
```

### solve-image

```bash
captchaflow solve-image ./captcha.png --json
```

Reads the image, base64-encodes it, submits an `ImageToTextTask`, polls until ready, prints the recognized text (or raw solution JSON with `--json`).

### recaptcha

```bash
# reCAPTCHA v2
captchaflow recaptcha https://example.com/login SITE_KEY

# reCAPTCHA v3 with a 0.9 minimum score
captchaflow recaptcha https://example.com/login SITE_KEY --v3 --score 0.9
```

Prints the `gRecaptchaResponse` token (or raw solution JSON with `--json`).

### hcaptcha

```bash
captchaflow hcaptcha https://example.com/signup SITE_KEY --json
```

### turnstile

```bash
captchaflow turnstile https://example.com/protected SITE_KEY
```

Prints the Turnstile `token`.

### Global flags

```bash
captchaflow --base-url https://captcha.dataleads.pro/v1 --key ALT_KEY balance
```

## Notes

- Tasks are created via `POST /createTask` and polled via `POST /getTaskResult` every 3 seconds (120 s max).
- Errors (non-zero `errorId`) raise a clean CLI error with the API's `errorCode`/`errorDescription`.
- Library use: `from captchaflow_cli import CaptchaFlowClient`.
