v0.x · MIT · Rust
Drop-in replacement with automatic anti-bot bypass. Same flags. Same exit codes. Same scripts. The 403 just stops happening.
# npm · pip · brew · cargo — pick your packager.
# no proxy. no API key. no monthly bill.
# install
# npm / npx
npm i -g recurl-cli
# PyPI
pip install recurl-cli
# Homebrew
brew tap neul-labs/tap brew install recurl
# Cargo
cargo install recurl
# what you get
recurl wraps a real curl binary and passes every standard flag through verbatim. Alias curl=recurl and your shell scripts, CI jobs, and Makefiles keep working — they just stop failing on bot-protected hosts.
First attempt is upstream curl, fast and low overhead. If the response is a 403, 429, or a captcha challenge, recurl escalates — TLS fingerprint impersonation, then headless Chromium with a cookie replay. Successful requests never pay the bypass cost.
On Linux and macOS, recurl bundles curl-impersonate profiles for Chrome, Firefox, Safari, and Edge. The TLS handshake, HTTP/2 SETTINGS frame, and pseudo-header order all match a real browser. Picks the profile automatically; force one with --recurl-impersonate.
For sites with JS challenges, recurl spins up Chromium, solves the challenge, captures cookies and tokens, then replays the request through curl. The result is the response your scripts wanted, in the format they already expect.
A background daemon holds a warm Chromium instance and reuses it across invocations. First request pays the boot cost; the next 50 do not. Idle timeout is configurable; the daemon shuts itself down when nothing is calling.
--recurl-debug prints which layer ran, why it escalated, what fingerprint was used, and what the upstream returned at each step. No more guessing why a request that worked yesterday returns a captcha today.
Security researchers and compliance scanners often want to know exactly what plain curl saw. --recurl-strict disables all fallback and gives you pure passthrough — same exit code, same body, same headers as upstream curl.
# how it works
Each layer only runs if the previous one was blocked. The successful path is the cheapest one, every time.
01 · curl_engine
recurl execs upstream curl with every flag you passed. If you get a 2xx, we are done — total overhead is one process boundary.
02 · impersonation
On 403/429/captcha, retry through curl-impersonate with a browser-matching JA3/JA4 handshake, HTTP/2 SETTINGS, and headers. Linux and macOS only.
03 · js preflight
Still blocked? Spin up Chromium via recurld, solve the challenge, capture cookies, replay through curl. You get the response your script expected.
# who uses it
Your scripts work in dev and 403 in prod. recurl removes the difference.
CI jobs that hit external APIs are flaky. They stop being flaky.
Test your own properties with browser-grade fingerprints, then flip --recurl-strict for the raw signal.
When monitoring curl gets a 403 from a vendor, recurl tells you whether it is fingerprinting or a real outage.
# honest comparisons
Two grounded comparisons. We skip Playwright and Selenium on purpose — they are a different category and we use them as a layer, not a competitor.
The baseline. recurl runs real curl on the happy path and only escalates on a block. Same flags, same exit codes — strictly more powerful with no added cost on success.
The closest open-source competitor. recurl wraps it. We add automatic block detection, JS preflight escalation, a warm daemon, and a fallback to plain curl on success.
# faq
Yes. recurl wraps a real curl binary and forwards every standard flag unchanged. Alias curl=recurl and existing scripts keep working. The recurl-specific behaviour lives behind a --recurl-* namespace that does not collide with anything curl already uses.
When the first attempt looks blocked. Today that means HTTP 403, HTTP 429, or a recognised challenge response. Successful requests return immediately with no overhead — there is no proxy, no browser, no daemon involved on the happy path.
A recurl binary, a background daemon called recurld, and bundled curl-impersonate binaries on Linux and macOS. Chromium is downloaded on first use of the JS preflight layer. Cargo, Homebrew, npm, and pip installs are all supported.
Yes, with one caveat. The TLS impersonation layer relies on curl-impersonate, which is Linux/macOS only today. On Windows, recurl skips the impersonation layer and goes straight to the JS preflight layer when a request looks blocked.
Yes, MIT licensed. The source lives at github.com/neul-labs/recurl. Issues, PRs, and contributions to the bypass detector are all welcome — the more real-world failures we see, the smarter the escalation gets.
Because most of your traffic does not actually need a browser. A headless browser is the right tool when you need to interact with rendered DOM. For everything else — APIs, JSON endpoints, file downloads, status checks — paying the Chromium overhead per request is wasteful. recurl pays it only when it has to.
No. recurl is a tool for engineers who already have legitimate access to the data they are fetching — public APIs, your own staging environments, sites you are authorised to scrape, security testing of your own properties. Same ethical scope as curl itself. Use it accordingly.
curl-impersonate is the closest open-source competitor and recurl uses it internally. The difference: curl-impersonate forces you to pick a TLS fingerprint up front and gives up if the site still blocks. recurl detects the block, escalates to JS preflight automatically, and falls back to plain curl on success. See the comparison page for the full table.
Install recurl, alias it as curl, and move on with your day. If it does not work, file an issue — the bypass detector improves every time we see a new failure.