- TypeScript, zero runtime dependencies. Native
fetch,node:utilparseArgs,node:fs,node:crypto,node:test. - The published package ships compiled JS in
dist/(runs on Node 20+). - For development, Node 23.6+ runs the
.tssources directly (type stripping).
src/cli/ router + commands + asset-command factory
src/core/ auth, config, policy, workspace, capabilities, registry, http, artifacts, errors, logger
src/adapters/ protected-fetch, extract
src/installers/ MCP client config generators
registry/ capabilities.json + <type>.json asset manifests
skills/ templates/ workflows/ recipes/ evals/ shipped assets
tests/ node:test suites
npm install # dev deps only (typescript, @types/node)
npm run dev -- --help # run the CLI from source
npm test # node --test
npm run typecheck # tsc --noEmit
npm run build # tsc → dist/- Add/flip its entry in
registry/capabilities.json. - Implement the adapter in
src/adapters/. - Wire the command (
src/cli/commands/) — guard withassertUsable(<key>). - Add a skill + recipe/eval and declare
requires_backend_capabilities. - Add tests. Never fake backend behavior; return a normalized error instead.
tests/e2e/crawl.e2e.test.ts drives the built CLI (zenrows crawl …) against a
live Zenrows API: it creates one small crawl of the target you give it (depth 1,
3 items, 5 pages, HTML output), waits for it, reads its results, one page's
HTML and the NDJSON export, lists crawls, stops the ended crawl and checks a
missing id. It is not part of npm test, and it skips unless ZENROWS_E2E=1,
ZENROWS_API_KEY and ZENROWS_E2E_CRAWL_URL are all set. It bills a few
pages on the key's account.
| Variable | Value |
|---|---|
ZENROWS_E2E |
1 to run the test |
ZENROWS_API_KEY |
a key with Crawl access |
ZENROWS_E2E_CRAWL_URL |
the start URL to crawl, e.g. https://example.com/products/ |
ZENROWS_E2E_CRAWL_INCLUDE |
optional include pattern, e.g. /product/; every result URL must contain it |
ZENROWS_CRAWL_API_BASE |
optional API base, default https://api.zenrows.com/v1 |
Read the key from a file rather than typing it, so it stays out of your shell history:
export ZENROWS_API_KEY="$(tr -d '\n' < path/to/api.key)"
ZENROWS_E2E=1 ZENROWS_E2E_CRAWL_URL=https://example.com/products/ \
ZENROWS_E2E_CRAWL_INCLUDE=/product/ npm run test:e2eTo target a local or staging deployment, set ZENROWS_CRAWL_API_BASE to its
/v1 base. When the account has reached its limit of active jobs (3 by
default, shared with its Batch jobs), the test waits retry_after seconds and
retries the create for up to 5 minutes, so run concurrent e2e
runs on one account one at a time.
Merge PRs with Conventional Commit titles, for example fix(crawl): ... or
feat(extract): .... fix, feat and perf need a scope.
After each merge to main, release-please opens or updates the PR
chore: release X.Y.Z. It sets the version in package.json,
package-lock.json and CLI_VERSION in src/core/config.ts, and adds the
release's entry to CHANGELOG.md. Do not change these by hand.
To list a change under "Behaviour Changes" in the changelog, end the PR body with an override block. release-please reads it in place of the squashed commit message, one Conventional Commit per line:
BEGIN_COMMIT_OVERRIDE
feat(fetch): add --retries, off by default
behaviour(fetch): what a user now sees differently
END_COMMIT_OVERRIDE
To release, merge that PR. The workflow runs the checks, creates the tag
vX.Y.Z and the GitHub release, and publishes @zenrows/cli to npm.
To publish an existing tag again, run the Release workflow by hand from
main with that tag.
The release PR runs CI like any other PR. After you merge it, the release
run checks the code again before it tags and publishes. If that check
fails, main already has the new version, but there is no tag, and the
merged release PR keeps the autorelease: pending label, which blocks the
next release PR. To recover:
- Fix the problem in a normal PR and merge it.
- Create the release on that fix commit, with the version from
.release-please-manifest.json:gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag> - On the merged release PR, replace the label
autorelease: pendingwithautorelease: tagged. - Run the Release workflow by hand from
mainwith the tagvX.Y.Z.
- Never print or persist API keys. Redact secrets in logs and artifacts.
- Every error must be agent-actionable:
code,message,likely_cause,next_action, optionalsuggested_commands. - Don't ship deceptive competitor benchmarks; evals must be reproducible.