Verbatim flag passthrough
Every standard curl flag — -s, -H, -d, -o, --resolve, exit codes and all — is forwarded unchanged to the wrapped upstream curl. Your Makefiles, CI jobs, and muscle memory keep working.
← back home · # features
Everything recurl does, layer by layer.
recurl is a debugger's curl, not a magic wand. Each capability below maps to one of the four things it actually does: stay compatible, detect blocks, impersonate a browser, and — only if it must — drive a headless browser. See the architecture for how they chain.
# drop-in curl compatibility
Same flags. Same exit codes. Same scripts.
recurl wraps a real curl binary and forwards every standard flag verbatim. Aliasing curl to recurl is the whole migration.
Namespaced recurl flags
recurl-specific behaviour lives behind a --recurl-* namespace that never collides with a real curl flag, so existing command lines stay valid.
Strict passthrough mode
--recurl-strict disables all fallback and gives you pure plain-curl behaviour — same exit code, same body, same headers — when you need the raw signal.
Multi-platform install
One binary via npm, PyPI, Homebrew, or Cargo. Linux, macOS, and Windows are all supported.
# automatic block detection
Plain curl first — escalate only when blocked.
The happy path is upstream curl, fast and side-effect free. recurl only pays the bypass cost when it actually sees a block.
Cheapest path wins
A 2xx from plain curl returns immediately — the total overhead is one process boundary. Successful requests never touch impersonation or a browser.
Block signal recognition
recurl recognises 403, 429, and known challenge response bodies as blocks and escalates automatically, with no per-host configuration.
Layer-by-layer debug trace
--recurl-debug prints which layer ran, why it escalated, which fingerprint was used, and what each upstream attempt returned — no more guessing.
Honest exit codes
When every layer is exhausted, recurl surfaces a real failure instead of pretending success, so your monitoring and pipelines stay trustworthy.
# tls fingerprint impersonation
Browser-grade JA3/JA4 handshakes.
On Linux and macOS recurl bundles curl-impersonate profiles so the TLS handshake, HTTP/2 SETTINGS frame, and pseudo-header order all match a real browser.
Real browser profiles
Chrome, Firefox, Safari, and Edge profiles (plus version variants) reproduce the exact handshake a WAF expects from that browser.
Automatic profile selection
recurl picks a fitting profile automatically on escalation. Force a specific one with --recurl-impersonate when a host only accepts a particular fingerprint.
Full-stack fingerprint match
It is not just the User-Agent — the JA3/JA4 TLS signature, HTTP/2 SETTINGS, and header order all line up, which is what a plain curl cannot do.
curl-impersonate underneath
recurl uses the well-established curl-impersonate as its impersonation layer, then adds detection and fallback on top.
# headless-browser preflight escalation
Chromium, only when fingerprints are not enough.
For JavaScript challenges, recurl spins up headless Chromium via the recurld daemon, solves the challenge, captures cookies, and replays through curl.
Challenge solving + cookie replay
The preflight solves the JS challenge, captures cookies and tokens, then replays the original request through curl so your parser sees the expected format.
Warm daemon (recurld)
recurld keeps a warm Chromium instance and reuses it across invocations. The first request pays the boot cost; the next fifty do not.
Tunable waits and timeouts
--recurl-js-wait waits for a CSS selector, --recurl-js-timeout adjusts the default 30s budget, and --recurl-js-rendered returns the rendered DOM when a replay is not enough.
Configurable idle shutdown
The daemon shuts itself down after a configurable idle timeout, so nothing lingers when you are not calling it.
See it in context.
Walk the escalation architecture, read the use cases, or follow a step-by-step guide.