Zenrows CLI
Zenrows CLI is the open-source command-line, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.
It makes the four Zenrows primitives — Fetch, Extract, Batch, and Browser Sessions — installable and usable directly from AI agents and developer workflows — so an agent can reliably access protected web data without hand-rolling anti-bot handling, proxies, or browser rendering.
1. What this is
A single, dependency-light CLI (zenrows) plus an installable asset registry
(skills, templates, workflows, recipes, evals) and MCP configuration for popular
agent clients. It makes Zenrows installable, usable, testable, and distributable
through AI agents, developers, and teams.
2. Why Zenrows
Normal fetch fails. Generic scrapers fail. Browser-first tools are expensive. Zenrows Fetch retrieves protected pages reliably and Extract structures them, while Browser Sessions are there for the rare cases that need a real browser. Zenrows wins when the workflow runs over thousands or millions of URLs.
3. Product architecture
The core product is Zenrows Fetch and Extract
(GET https://api.zenrows.com/v1/). The CLI exposes it two ways: zenrows fetch
retrieves a protected page, and zenrows extract turns it into structured data
(JSON / CSS / Markdown). Both call the same endpoint — extract is just
that endpoint with extraction parameters, not a separate product.
The CLI maintains a capability matrix (registry/capabilities.json). Every
command checks status before any cloud call, so the toolkit never fakes behavior
for primitives the backend does not expose. Run zenrows status for the live
matrix.
4. Quickstart
npm install -g @zenrows/cli # puts `zenrows` on PATH (466 ms, zero deps)
zenrows init
zenrows fetch https://httpbin.io/html # auto-provisions a Free plan account on first use
zenrows extract https://www.owler.com/company/meltwater # extract=auto on a prepared domain
zenrows extract https://www.scrapingcourse.com/ecommerce/ --css '{"title":"h1"}' # CSS selectors (any domain)
Prefer no global install? Prefix each command with
npx -y @zenrows/cli(e.g.npx -y @zenrows/cli fetch <url>) —npxdoes not putzenrowson PATH.
No API key up front: on your first cloud call the toolkit creates a free, unclaimed Zenrows Free plan account for you (see §6).
5. Install everything
zenrows init --all # workspace + config + policy + assets + MCP snippets + health check
zenrows init --agents claude-code,codex,cursor,gemini,opencode,windsurf,vscode
If a requested target cannot be auto-configured, the toolkit prints explicit manual instructions rather than silently skipping it.
6. Zero-config access, signup & claim
You do not need an API key to get started. On your first cloud call
(e.g. zenrows fetch <url>), the toolkit automatically creates a free,
unclaimed Zenrows Free plan account, stores the key in .zenrows/secrets.json
(0600, gitignored), and records the account in .zenrows/account.json
(no secret — just the accountId, Free-period info, and a claim link).
Zenrows may first ask the agent one short question before it creates the
account. The command then fails with SIGNUP_CHALLENGE and prints the
question; answer it and re-run the original command:
zenrows signup --answer "<your answer>"
A wrong or late answer gets a new question. Too many questions or wrong
answers from one network pause signups there for an hour
(SIGNUP_CHALLENGE_LOCKED).
When you (or your agent) want to keep the usage and history, claim the account — this confirms an email (Google, GitHub or a 6-digit code); the same key keeps working:
zenrows account status # show account + Free period + claim link
zenrows account claim # open the claim URL (fresh one if the stored link is near its 30-day expiry)
zenrows usage # plan usage, credits & concurrency (does not count against your limit)
Opt out of auto-provisioning at any time:
zenrows fetch <url> --no-signup # do not auto-create an account for this call
zenrows signup --agent # explicitly provision a Free plan account, headless
zenrows signup --answer "<text>" # answer the signup question (SIGNUP_CHALLENGE)
zenrows login --api-key <key> # use an existing key (stored 0600, gitignored)
zenrows login --env # use the ZENROWS_API_KEY environment variable
Set auto_signup: false in .zenrows/policy.json to disable auto-provisioning
globally.
7. Protected Fetch
zenrows fetch <url> # Adaptive Stealth Mode (mode=auto)
zenrows fetch <url> --output markdown
zenrows fetch <url> --manual --js-render --premium-proxy
zenrows fetch <url> --proxy-country us --wait-for ".price"
8. Extract
zenrows extract https://www.owler.com/company/meltwater # extract=auto (prepared domain)
zenrows extract https://www.scrapingcourse.com/ecommerce/ --autoparse # deprecated Autoparse (any domain)
zenrows extract <url> --css '{"title":"h1","price":".price"}' --validate
zenrows extract <url> --outputs emails,links # built-in output filters → JSON
zenrows extract <url> --output markdown
On a domain Extract hasn't prepared yet, zenrows extract fails with
EXTRACT_DOMAIN_NOT_PREPARED (API code REQS007) and prints the command to
prepare it. Preparing takes a few minutes and costs no credits; each new domain
uses one slot of the monthly allowance. EXTRACT_PAGE_NOT_RECOGNISED (also
REQS007) is different: the domain is prepared, but this page is not one Extract
extracts. Try a product, article or listing page instead, retry it once in a
few minutes if it should work, or use --css; preparing again does not change
it. zenrows extract never falls back to Autoparse. The fallbackAutoparse
adapter option is deprecated and has no effect.
Pass 1 to 5 example URLs. One works; we recommend 3 or more of the same page type (e.g. 3 product pages), because Extract compares pages of one type to check the fields it found and fill in fields one page is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result pages).
zenrows extract prepare example.com \
--url https://www.example.com/products/a \
--url https://www.example.com/products/b \
--url https://www.example.com/products/c --wait
zenrows extract prepare status example.com # progress + monthly allowance
zenrows extract https://www.example.com/products/a # then extract again
9. Batch
Zenrows Batch (https://async.api.zenrows.com/v1) fans a
protected fetch/extract out over many URLs. The cloud subcommands work
with any active API key and cost the same credits as Fetch: Batch is the
reliable path at scale, at Fetch's prices. Local spec validation + credit
estimation always work (no key needed).
zenrows batch estimate jobs.jsonl # validate the spec + estimate credits (local)
zenrows batch create jobs.jsonl --follow # submit a job and wait for it to finish
zenrows batch list # your jobs, newest first
zenrows batch status <job-id> # run status, progress stats, pause state
zenrows batch wait <job-id> --timeout 30m # wait for the run to end
zenrows batch results <job-id> --out results.jsonl # collect results (paginated)
zenrows batch content <job-id> <task-id> # one task's result body
zenrows batch pause <job-id> # pause the run (resume <job-id> continues it)
zenrows batch cancel <job-id> # stop an in-flight run
zenrows batch retry-failed <job-id> --include-pending # rerun every task that did not succeed
zenrows batch rerun <job-id> # rerun failed + pending tasks (--all: every task)
zenrows batch delete <job-id> --yes # delete the job, its runs and results
jobs.jsonl is one JSON object per line, each with a url (plus optional
per-line overrides like js_render, premium_proxy, proxy_country,
extract, nested zenrows_params, an external_id, string metadata, and
"method": "POST" with a body of up to 16 KiB). estimate and create
check every line against the API's limits before anything is sent: url up
to 2048 bytes, external_id up to 128 letters, digits, ., _ or -,
and metadata up to 20 string entries (4 KiB). Validate and estimate locally
first, then submit with create. estimate takes create's
--manual / --js-render / --premium-proxy / --proxy-country flags and
prices the same request, as a range (Adaptive Stealth Mode costs 1 to 25).
create also takes --name, --external-id and --metadata key=value
(repeatable) for the job itself. It sends an Idempotency-Key (generated, or
--idempotency-key) and retries network errors and 502/503/504 under it; an
outcome that stays unknown prints the command that repeats the request with
that key, which cannot create a second job.
The local policy caps a run at 10,000 URLs and 250,000 estimated credits by
default (an Adaptive Stealth Mode task counts 25), so a default run of up to
10,000 URLs passes in any mode. Raise them for larger jobs (the API takes up to
100,000 tasks per job): zenrows policy set max_pages_per_run 100000 and
zenrows policy set max_credits_per_run 2500000. A workspace created by an
earlier version keeps its caps (1,000 and 10,000) in policy.json.
wait, create --follow and rerun --follow poll until the run ends, the run
is paused, or --timeout runs out (default 10 minutes; 30s, 5m, 1h; a
bare number is milliseconds, as before). When the time runs out, or the run is
paused, the command exits 0 and prints the run with a note and the next
command; the job keeps running. Ctrl-C stops the wait, not the job, and exits
130. A run that ends failed exits 1: out of credits is
POLICY_MAX_CREDITS_EXCEEDED, an inactive subscription AUTH_INVALID, a key
cap KEY_CREDIT_CAP_REACHED (the same codes a refused request gets), anything
else BATCH_FAILED, each with the run's failure_reason as server_code and
the job_id. Then run the unfinished tasks with
zenrows batch rerun <job-id> --status failed,pending,processing. With no
flag, rerun reruns the failed and pending tasks, so successful tasks are
never billed again by surprise; --status <list> picks the statuses and
--all reruns every task (not with --status). A partial rerun works for 10
days after the run started; --all always does.
With --json, create, status, wait, cancel, pause, resume and
rerun print {ok, job_id, run_id, status, stats, job} (jobId is kept for
older scripts), plus paused, ingest_status, accepted_tasks, rerun_of,
retried_tasks and inherited_tasks when the API sends them. Results are
kept 14 days by default and then read expired; a result_url is valid 2
hours. Lifecycle errors get their own codes (BATCH_RUN_IN_PROGRESS,
BATCH_NO_MATCHING_TASKS, BATCH_RERUN_WINDOW_EXPIRED,
BATCH_REQUEST_IN_FLIGHT, BATCH_RESULT_EXPIRED, ...) and carry the API's code
as server_code. Schedules, webhooks, ZIP exports, CSV inputs and open jobs
are available through the Batch API and the SDKs, not this CLI.
Extract in Batch. Set "extract": "auto" on a line to run that URL through
Extract — structured data instead of raw HTML:
{"url": "https://example.com/products", "extract": "auto", "external_id": "p1"}
{"url": "https://example.com/reviews", "extract": "auto", "external_id": "r1"}
An Extract task costs the same as a regular one (1 credit at base tier), so
batch estimate prices it correctly. Results for an Extract task carry two
keys: html (the raw page) and parsed (the structured data) — validate a
sample with zenrows extract <url> before running the full batch.
10. Crawl (new)
Crawl is still evolving: new features are coming, limits may be tuned, and the changelog announces each change.
Crawl (https://api.zenrows.com/v1/crawls)
takes one start URL and returns the URLs it finds behind it, optionally with
each page's HTML. Use it when you know the listing or section but not the item
URLs. Crawl follows the links on each page, up to --depth hops when you set
it, and stays on the start URL's registrable domain (subdomains count). Without
--output-format html it returns URLs only. An account without Crawl access gets
CRAWL_NOT_ENABLED ("Crawl is not enabled for this account", HTTP 403
REQS008).
zenrows crawl create https://example.com/products/ --depth 1 \
--max-items 20 --include-patterns /product/ --follow # create and wait for the end
zenrows crawl results <crawl-id> --out urls.jsonl # every kept URL (paginated)
zenrows crawl create <url> --depth 2 --output-format html # also fetch each kept page's HTML
zenrows crawl content <crawl-id> <content-id> # one page's HTML
zenrows crawl download <crawl-id> # NDJSON export (URLs + HTML) → <crawl-id>.jsonl
zenrows crawl get <crawl-id> # status, coverage, stop reason, one page of results
zenrows crawl wait <crawl-id> # wait for the end
zenrows crawl list # your crawls, newest first
zenrows crawl stop <crawl-id> # stop a running crawl
--depth (link hops, 1 to 100000) is optional: leave it out and the crawl
follows links until --max-items or --max-pages stops it, or nothing is left
to open. --max-items and --max-pages cap the crawl (API default 100 each),
and --max-pages bounds the cost, since each page is one fetch. The local policy max_pages_per_run caps --max-pages (default
10000). --output-format html uses up the page budget: each kept page is one
more fetch, and --max-pages counts it. --include-patterns /
--exclude-patterns are repeatable substring filters on the URL. A crawl whose
pages held nothing new to follow ends completed with no results and exits 0.
When patterns were set, it prints a note (under --json, in note) to check
them against the URLs the start page links to. get and
list read one page and take --cursor and --limit. results follows every
page (--limit is the page size); on a running crawl it returns the URLs kept
so far, with partial: true. download reports the crawl's status (null
when the API sends none), and partial: true while it runs.
With --json, create, get, wait and stop print
{ok, crawl_id, status, crawl}. The crawl object (with coverage,
stop_reason and error) is under crawl. get adds results and
next_cursor. All keys are snake_case.
wait, and create --follow, poll until the crawl ends or --timeout seconds
run out (default 600). When the time runs out, the command exits 0 and prints
the crawl with status running and the hint zenrows crawl wait <crawl-id>
(under --json, in note); the crawl keeps running. Ctrl-C stops the wait, not the crawl, and exits 130;
resume with zenrows crawl wait <crawl-id>. A crawl that ends failed exits 1
with CRAWL_FAILED. A crawl that ends stopped because the account ran out of
credits or the API key hit a credit cap also exits 1, with the code a refused
create gets: CRAWL_INSUFFICIENT_CREDITS or CRAWL_KEY_CAP_REACHED, and the
API's insufficient_credits or api_key_cap_reached as server_code. Older
deployments end such a crawl failed; it gets the same codes. Its fetched pages
stay readable.
Errors carry the API's code as server_code, crawl_id on any call about one
crawl, and retry_after on a 429. When the account has reached its limit of
active jobs (3 by default), shared with its Batch jobs, a create gets 429
too_many_crawls, mapped to CRAWL_TOO_MANY_CRAWLS, and creates nothing; retry
after retry_after seconds. Any other 429 is CRAWL_RATE_LIMITED: requests
are being throttled; retry after retry_after seconds. Other codes: CRAWL_INSUFFICIENT_CREDITS and CRAWL_KEY_CAP_REACHED (402, with the
same claim, top-up and key-cap advice as other commands),
CRAWL_INVALID_REQUEST (400/422, do not retry as is), CRAWL_REQUEST_IN_FLIGHT
(409, retry once the first request ends), CRAWL_NOT_FOUND,
CRAWL_CONTENT_NOT_FOUND, CRAWL_BUSY (503 on a stop that was not saved yet;
run it again, it is safe) and CRAWL_FAILED. Set ZENROWS_CRAWL_API_BASE to
point the CLI at another deployment.
The CLI retries transient failures, as the Crawl SDKs do: up to 3 retries,
waiting the Retry-After seconds (at most 30) or 250 ms x 2^n (+/-20% jitter,
at most 10 s).
Reads retry on 429, 502, 503, 504 and network errors (a timeout counts).
create retries only with --idempotency-key, and only on 502, 503, 504 and
network errors, never on 429. stop retries on 429, 502, 503 (a crawl_busy
means the stop was not saved and the crawl still runs) and 504, waiting the
Retry-After seconds (at most 30) or 1 s; repeating a stop is safe.
11. Browser Sessions
Escalation only — prefer fetch/extract for the vast majority of cases;
they cost less. Use the browser for logins, forms, and multi-step JS flows that
Protected Fetch can't handle. Drives the managed Browser Sessions REST API
(mcp.zenrows.com/browser/sessions/*, same backend as the @zenrows/mcp
browser_* tools). zenrows browser connect prints the raw CDP wss URL for
bring-your-own Playwright/Puppeteer.
Billing & lifecycle: sessions bill by bandwidth + session time and
auto-terminate after 15 minutes — run <script.json> closes automatically;
close interactive sessions with zenrows browser close. On by default; opt out
with zenrows policy set allow_browser false.
12. MCP
zenrows mcp status
zenrows mcp config --client claude-code # exact `claude mcp add` command
zenrows mcp config --client cursor # mcpServers JSON
zenrows mcp config --client vscode # servers JSON
zenrows mcp config --client generic --remote # hosted server at https://mcp.zenrows.com/mcp
Local server: npx -y @zenrows/mcp (stdio; can auto-provision a Free plan key).
Remote server: https://mcp.zenrows.com/mcp (streamable-http; client OAuth).
The portable Agent Plugins package at agent-plugin/ declares
both servers in mcp.json (no secrets) and ships MCP-native skills under
agent-plugin/skills/. It is included in the published @zenrows/cli npm
tarball (node_modules/@zenrows/cli/agent-plugin).
13. Plugins
zenrows plugin list
zenrows plugin install claude-code # installs core skills + prints MCP config
Agent Plugins 1.0: after npm install @zenrows/cli, use
node_modules/@zenrows/cli/agent-plugin/ (plugin.json + mcp.json +
MCP-native skills). See agent-plugin/README.md.
Legacy per-client snippets from zenrows plugin install remain available.
CLI-oriented skills stay under repo-root skills/.
14. Skills
Agent-readable playbooks that teach agents how to choose primitives.
zenrows skill list
zenrows skill install --all
zenrows skill validate zenrows
The master skill skills/zenrows/SKILL.md teaches the full decision tree.
15. Templates
zenrows template list
zenrows template create protected-fetch-node --output ./my-project
16. Workflows
zenrows workflow list
zenrows workflow explain competitor-intelligence
17. Recipes
zenrows recipe list
zenrows recipe run fetch-protected-page
18. Evals
Reproducible, transparent benchmarks. No competitor keys are bundled and nothing is hardcoded to make Zenrows win — comparison evals require you to supply your own credentials.
zenrows eval list
zenrows eval run protected-fetch-smoke
zenrows eval report protected-fetch-smoke
Reports write input.json, results.json, report.md, failures.jsonl,
cost.json, and traces/ under .zenrows/evals/<run-id>/.
19. Security
- API keys are never printed or written into run artifacts/assets.
- Secrets live in
.zenrows/secrets.json(0600, gitignored); logs are redacted. .zenrows/account.jsonholds no secret — only the accountId, Free-period info, and claim link..zenrows/policy.jsonenforces credit/page/concurrency limits and domain allow/deny.- Destructive
uninstallrequires--yes. Browser is on by default; opt out withzenrows policy set allow_browser false. Experimental features are off by default.
20. Capability matrix
See registry/capabilities.json. zenrows status --json emits it.
21. Contributing
The CLI is TypeScript with zero runtime dependencies (native fetch,
node:util parseArgs, node:test). Node 20+ runs the published build;
Node 23.6+ runs the TypeScript sources directly for development.
Zenrows is building the protected web data infrastructure layer. The Zenrows CLI is how that infrastructure becomes native to AI agents.
