CurlWright

Execute curl requests through a real Playwright browser when anti-bot protection gets in the way

Overview

CurlWright is a Python tool that takes a curl command, opens a real Google Chrome browser through Patchright (a stealth-patched Playwright), works through Cloudflare and similar browser-side friction, and returns the final HTTP response in a form that still feels close to curl-driven workflows.

It is useful when a plain HTTP client is not enough because the target requires browser execution, JavaScript, cookies, challenge handling, or a persisted trusted session.

On the Cloudflare bypass: CurlWright drives real Google Chrome (channel="chrome") with Patchright's protocol-level stealth (navigator.webdriver hidden, no CDP Runtime.enable leak), so it transparently handles passive Cloudflare (CDN) and has a real shot at managed / "I'm Under Attack" / non-interactive challenges.

Run headed for the best results. The default (no --headless/--no-gui) launches a visible Chrome with a genuine, consistent fingerprint — the strongest stealth. --no-gui/--headless use Chrome's new headless for servers/CI, but the browser still advertises HeadlessChrome in its user agent, which strict bot-management may flag; on a VPS, run under xvfb for headed-quality stealth.

Hardened managed challenges → --engine nodriver. The default Patchright engine clears passive CF and Turnstile, but the toughest "Just a moment" managed challenges fingerprint Playwright's automation-protocol signature (Runtime.enable/Target.setAutoAttach) and stall at HTTP 403. Pass --engine nodriver to drive Chrome over a plain CDP WebSocket (no such signature), which clears those interstitials. nodriver requires headed mode (omit --headless); headless is detected just like Patchright. A flagged/datacenter IP still gets blocked regardless of engine — use a residential proxy via curl -x.

It is not a guaranteed solver for every hardened anti-bot setup — some still require a paid CAPTCHA service, which CurlWright does not bundle. It detects the challenge type and progresses what it can; when a page cannot be cleared it fails loudly with diagnostics (exit code 10).

Key Features

Supported curl Inputs

Methods       -X/--request, -I/--head, -G/--get
Headers       -H/--header
Body          -d/--data, --data-raw, --data-binary, --data-urlencode
Cookies       -b/--cookie
Auth          -u/--user
Network       -x/--proxy, -L/--location, -k/--insecure, --max-time
Input Forms   Direct command (-c) or file (-f)

Installation

From PyPI (Recommended)

pip install curlwright
# CurlWright drives your system Google Chrome (channel="chrome").
# If you do not have Chrome installed, fetch a Chrome build for Patchright:
patchright install chrome

Requires Google Chrome on the host (the default channel="chrome"). On a server/VPS, install Chrome (or run patchright install chrome); headless runs use Chrome's new headless mode.

From Source

git clone https://github.com/seifreed/Curlwright.git
cd Curlwright
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
patchright install chrome   # only if system Chrome is absent

Quick Start

# Execute a curl command directly
curlwright -c "curl https://example.com"

# Read the curl command from a file
curlwright -f request.txt

# Emit structured JSON for automation
curlwright -f request.txt --json-output

Usage

Command Line Interface

# Basic request
curlwright -c "curl https://httpbin.org/get"

# Save the response body to a file
curlwright -f request.txt -o response.html

# Server/CI mode
curlwright -f request.txt --no-gui --json-output

# Persist diagnostics for failures
curlwright -f request.txt --artifact-dir .artifacts/run-1 --sarif-output report.sarif

# Increase retries and timeout
curlwright -c "curl https://target.example" --timeout 60 --retries 5 --delay 3

Available Options

Output Contracts

--json-output emits a stable machine-readable structure:

{
  "schema_version": 1,
  "kind": "curlwright-result",
  "ok": true,
  "exit_code": 0,
  "response": {
    "status": 200,
    "url": "https://example.com/",
    "headers": {},
    "body": "..."
  },
  "meta": {}
}

Failure JSON includes error, error_type, exit_code, and for bypass failures also artifact_dir plus an assessment block.

Python Library

Basic Usage

import asyncio

from curlwright import RequestExecutor


async def main() -> None:
    executor = RequestExecutor(headless=True, timeout=30)
    result = await executor.execute('curl -H "Accept: application/json" https://httpbin.org/get')

    print(result["status"])
    print(result["url"])
    print(result["body"][:120])

    await executor.close()


asyncio.run(main())

Parse curl Before Execution

from curlwright import CurlParser

parser = CurlParser()
request = parser.parse('curl -X POST -H "Content-Type: application/json" https://api.example.com')

print(request.method)
print(request.url)
print(request.headers)

Cookie Persistence

import asyncio

from curlwright import RequestExecutor
from curlwright.utils import CookieManager


async def main() -> None:
    cookies = CookieManager("cookies.json")
    executor = RequestExecutor(headless=True, cookie_file="cookies.json")
    result = await executor.execute("curl https://example.com")
    print(result["status"])
    await executor.close()


asyncio.run(main())

Examples

API Request Through A Browser Session

curlwright -c 'curl -H "Authorization: Bearer TOKEN" https://api.example.com/data' --json-output

Request File

Create request.txt:

curl -X GET \
  -H "Accept: application/json" \
  -H "User-Agent: Analyst/1.0" \
  -b "session=abc123" \
  https://protected.example.com/api/data

Run it:

curlwright -f request.txt -o response.json

CI-Friendly Execution

mkdir -p .artifacts/job-1

curlwright \
  -f request.txt \
  --no-gui \
  --json-output \
  --sarif-output .artifacts/job-1/curlwright.sarif \
  --artifact-dir .artifacts/job-1 \
  --state-file .artifacts/job-1/state.json \
  --cookie-file .artifacts/job-1/cookies.pkl \
  > .artifacts/job-1/result.json

Headless Retry-Tuned Request

curlwright -c "curl https://target.example" --headless --timeout 90 --retries 5 --delay 2

Architecture

The active codebase follows an explicit layered structure:

curlwright/
  domain/           Pure models, policies and ports
  application/      Use cases and orchestration
  infrastructure/   Playwright, persistence and parser adapters
  interfaces/       CLI, JSON and SARIF presenters
  bootstrap.py      Composition root

This separation keeps browser automation and heuristics in infrastructure while the policy and use-case flow stay isolated from Playwright details.

Requirements

• Python >=3.13,<3.15
• Playwright Chromium installed via python -m playwright install chromium
• See pyproject.toml for the full package metadata and dependency declarations

Contributing

Contributions are welcome. If you want to change behavior, add support for more curl flags, or improve challenge handling, open an issue or send a pull request.

1. Fork the repository
2. Create your branch: git checkout -b feature/my-change
3. Run the test suite
4. Commit your changes
5. Push the branch
6. Open a pull request

Support the Project

If CurlWright is useful in your workflows, you can support the project here:

License

This project is licensed under the MIT License. See LICENSE for details.

Attribution

• Author: Marc Rivero | @seifreed
• Repository: github.com/seifreed/Curlwright

_{Built for browser-backed automation and resilient protected-request workflows}