magnus919_agent-skills/flaresolverr-cli/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
flaresolverr-cli	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.	MIT	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).	tags sources flaresolverr, cloudflare, proxy, anti-bot, headless-browser, selenium, web-scraping 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):

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

2. Set the server URL:

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

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

Essential Commands

health — Server health check

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

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

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

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

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

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

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:

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 — Stdlib-only reference implementation for the same API.
• FlareSolverr GitHub — Source, API docs, Docker Compose examples.
• FlareSolverr Docker Hub — Prebuilt images.