flaresolverr-cli git:20260711.df1b527A

Immutable. This exact content is served forever at /api/v1/blob/7ce3e5b92b5c232c.

---
name: flaresolverr-cli
description: 'Interact with a FlareSolverr proxy server from the terminal: health
  checks, session lifecycle (create/list/destroy), and challenge-solving HTTP requests
  (GET/POST) through Cloudflare and DDoS-GUARD protection. Use when the user mentions
  FlareSolverr, Cloudflare bypass, anti-bot proxy, headless browser proxy, or needs
  to fetch a page behind Cloudflare protection.'
license: MIT
compatibility: >-
  Python 3.8+ (stdlib only, no pip deps). Requires a running FlareSolverr
  instance (Docker: ghcr.io/flaresolverr/flaresolverr) and the FLARESOLVERR_URL env
  var set to the server address (defaults to http://localhost:8191).
metadata:
  tags: flaresolverr, cloudflare, proxy, anti-bot, headless-browser, selenium, web-scraping
  sources: "https://github.com/FlareSolverr/FlareSolverr, https://hub.docker.com/r/flaresolverr/flaresolverr"
---

# flaresolverr-cli — Cloudflare Bypass Proxy from the Terminal

Drive a FlareSolverr instance from the command line. FlareSolverr is a proxy server that launches a headless Chrome browser to solve Cloudflare and DDoS-GUARD JavaScript challenges, returning the unblocked HTML, cookies, and user-agent to your client.

The CLI wraps all four API endpoints: service info, health check, the three `/v1` session commands (create/list/destroy), and both challenge-solving request commands (`request.get` and `request.post`). Every command supports `--json`, `--dry-run`, and `--timeout`.

## Setup

1. Start a FlareSolverr instance (Docker):

```bash
docker run -d --name=flaresolverr -p 8191:8191 \
  ghcr.io/flaresolverr/flaresolverr:latest
```

2. Set the server URL:

```bash
export FLARESOLVERR_URL="http://localhost:8191"
```

`--help` and `--dry-run` work without a running server.

## Essential Commands

### health — Server health check

```bash
flaresolverr-cli health                     # check if server is reachable
flaresolverr-cli health --json              # {"status": "ok"}
```

Calls `GET /health`. Returns `ok` when the server is running. Use as a readiness probe or pre-flight check before session/request commands.

### info — Service information

```bash
flaresolverr-cli info                       # version, user-agent, ready message
flaresolverr-cli info --json                # machine-readable
```

Calls `GET /`. Returns the FlareSolverr version, the Chrome user-agent string, and whether the service is ready to accept requests.

### sessions create — Create a persistent browser session

```bash
flaresolverr-cli sessions create                           # auto-generated session ID
flaresolverr-cli sessions create --session my-session      # custom session name
flaresolverr-cli sessions create --proxy socks5://proxy:1080  # with proxy
```

Creates a long-lived headless browser instance. Reuse the returned session ID in subsequent `request get` / `request post` calls for 10-100x faster requests (no browser startup overhead per call).

### sessions list — List active sessions

```bash
flaresolverr-cli sessions list              # all active session IDs
```

Returns the IDs of every active persistent session. Each session holds a browser process — use this to audit resource usage before creating more.

### sessions destroy — Tear down a session

```bash
flaresolverr-cli sessions destroy --session my-session
```

Closes the browser and frees memory. Always destroy sessions when done — each idle session consumes significant RAM.

### request get — Fetch a URL through the solver

```bash
flaresolverr-cli request get --url https://example.com                        # basic
flaresolverr-cli request get --url https://example.com --session my-session    # reuse session
flaresolverr-cli request get --url https://example.com --return-only-cookies   # cookies only
flaresolverr-cli request get --url https://example.com --timeout 120           # 120s timeout
```

Sends `request.get` to the `/v1` endpoint. FlareSolverr launches Chrome (or reuses a session), navigates to the URL, solves any Cloudflare/DDoS-GUARD challenge, and returns the resolved HTML, cookies, and user-agent.

Flags:

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--url` | string | required | Target URL |
| `--session` | string | — | Reuse existing session (faster) |
| `--max-timeout` | int | 60000 | Challenge solve timeout (ms) |
| `--return-only-cookies` | flag | false | Omit HTML from response |
| `--proxy` | string | — | Per-request proxy URL |
| `--wait` | int | 0 | Extra wait after solve (seconds) |

### request post — POST through the solver

```bash
flaresolverr-cli request post --url https://example.com/form --data "a=1&b=2"
```

Same as `request get` but sends an `application/x-www-form-urlencoded` POST body. Accepts the same flags plus `--data` (the form-encoded body string).

## Global Flags

All flags work in any position:

```bash
flaresolverr-cli --json health
flaresolverr-cli --dry-run sessions create --session test
flaresolverr-cli --quiet request get --url https://example.com
flaresolverr-cli --timeout 30 request get --url https://example.com
```

| Flag | Effect |
|------|--------|
| `--json` | Output one JSON value to stdout (all diagnostics go to stderr) |
| `--dry-run` | Print the planned API call without making it |
| `--quiet` | Suppress non-essential output |
| `--timeout N` | HTTP request timeout in seconds (default 60) |

## Known Gotchas

- **No authentication** — FlareSolverr has no built-in auth. Expose it only on localhost or behind a reverse proxy with auth.
- **HTTP 200 for errors** — FlareSolverr always returns HTTP 200. Check the JSON `status` field (`"ok"` vs `"error"`) to determine success.
- **Session proxy precedence** — When a `--session` is provided, any `--proxy` flag is ignored. The session's proxy (set at create time) takes precedence.
- **Memory per session** — Each persistent session runs a full Chrome browser (~200-500 MB RAM). Destroy sessions promptly.
- **First request latency** — A stateless request (no `--session`) pays a browser cold-start cost of 3-10 seconds. Persistent sessions amortize this.
- **POST body format** — `--data` must be `application/x-www-form-urlencoded` format (`key=value&key2=value2`). Multipart and JSON bodies are not supported by FlareSolverr.
- **Selenium status limitation** — The `status` field in responses is always 200 (Selenium does not expose the real HTTP status). Trust the response body, not the status code.

## References

- [Related FlareSolverr CLI](../flaresolverr/scripts/flaresolverr) — Stdlib-only reference implementation for the same API.
- [FlareSolverr GitHub](https://github.com/FlareSolverr/FlareSolverr) — Source, API docs, Docker Compose examples.
- [FlareSolverr Docker Hub](https://hub.docker.com/r/flaresolverr/flaresolverr) — Prebuilt images.