Prometheus
Reference

CLI reference

prometheus is a thin command-line wrapper over a running instance's HTTP API. Ask for verified Firecrawl code (build) or manage self-healing scripts and their deployments (scripts, deploy, deployments). Zero dependencies (Node ≥ 18, uses global fetch); it never embeds the agent — it just calls your instance.

Install

bash
# run without installing (from the repo)node cli/bin.mjs build "top 5 Hacker News stories"
# or install the `prometheus` command globallynpm i -g @firecrawl/prometheus-cli

Configuration

Env varDefaultPurpose
PROMETHEUS_URLhttp://localhost:3000Instance base URL.
PROMETHEUS_TOKEN—Bearer token, if your instance requires auth.
PROMETHEUS_DEBUG—If set, prints the full error payload on failure.
bash
export PROMETHEUS_URL=https://your-prometheus.example.comexport PROMETHEUS_TOKEN=sk-...

Output modes

Every command supports --json. The CLI is TTY-aware:

  • Interactive terminal: human-friendly output (tables, summaries; build writes files).
  • Piped or --json: raw JSON on stdout, so another program can parse it.

Errors print error: <message> to stderr and exit non-zero.

The model

A SCRIPT is the versioned collector (prompt, self-heal, marketplace lineage). A DEPLOYMENT is one way it runs for you: on a cron (--every), on demand as an API endpoint (--no-schedule), or both. One script can have many deployments.

prometheus build

Ask Prometheus for a verified Firecrawl collector.

bash
prometheus build "<prompt>" [--schema FILE] [--url URL]... [-o DIR] [--model P:ID] [--json]
FlagMeaning
--schema FILEPath to a JSON Schema file the output must match.
--url URLStarting URL (repeatable).
-o DIRDirectory to write script.ts + sample.json (TTY mode; default cwd).
--model P:IDModel override, e.g. anthropic:claude-opus-4-8 or openai:gpt-5.5.
--jsonEmit the raw API response instead of writing files.

Interactive — writes script.ts + sample.json and prints how it works:

bash
prometheus build "top 5 Hacker News stories with title, url, points"

Piped — feed the code straight into your project:

bash
prometheus build "latest stable npm version of react" --json | jq -r .script > scraper.ts

The returned script runs with tsx script.ts and needs FIRECRAWL_API_KEY. Builds run the agent and take ~30–180s.

prometheus scripts

Create and manage versioned, self-healing collectors.

bash
prometheus scripts create "<prompt>" [--every SCHED | --no-schedule] [--name N] [--heal STRAT] [--session ID] [--schema FILE] [--json]prometheus scripts ls [--json]prometheus scripts show <id> [-o script.ts] [--json]prometheus scripts data <id> [-o FILE]prometheus scripts heal <id> [--json]prometheus scripts fork <id> [--json]prometheus scripts rm   <id>

create

Provide a prompt (builds now) or --session <id> from a prior build (mints an existing collector instantly). --every / --no-schedule also deploy the new script in the same call.

bash
prometheus scripts create "OpenAI blog post titles + urls" --every daily@09:00 --name "OpenAI blog"prometheus scripts create --session build-XCFpO8Z… --every 6hprometheus scripts create "competitor pricing table" --no-schedule   # on-demand API endpoint only

Schedules (--every, UTC): hourly · 30m · 6h · daily · daily@14:00 · weekly · monday@09:00 · raw cron "0 9 * * 1". --no-schedule = on-demand only.

Self-heal (--heal): off · repair · rebuild · repair_then_rebuild (default). A successful heal appends a new script version that every track-latest deployment picks up.

ls / show

bash
prometheus scripts ls# ●  RxTLhAZ31…  HN top 5  v3#     ●  dXf91k…  Hourly pull  every hour  on
prometheus scripts show RxTLhAZ31…   # detail + deployments + versions

Health icons: ● healthy · ✗ failing · ↻ healing · ○ pending.

data

The latest collected JSON across all the script's deployments — the thing you actually consume.

bash
prometheus scripts data RxTLhAZ31… -o latest.json   # write to fileprometheus scripts data RxTLhAZ31… | jq '.articles[0]'   # or pipe

heal / fork / rm

bash
prometheus scripts heal RxTLhAZ31…   # repair/rebuild a broken script nowprometheus scripts fork RxTLhAZ31…   # stop tracking its marketplace listing (one-way)prometheus scripts rm   RxTLhAZ31…   # archive (soft delete; deployments included)

prometheus deploy / deployments

Operate the ways a script runs.

bash
prometheus deploy <scriptId> [--every SCHED | --no-schedule] [--name N] [--pin V] [--json]prometheus deployments ls [--json]prometheus deployments show <id> [--json]prometheus deployments run <id> [-o FILE]      # fresh data, synchronously (the API-endpoint trigger)prometheus run <id> --async --webhook URL      # 202 now; the signed outcome POSTs to your webhookprometheus deployments data <id> [-o FILE]     # last collected dataset, no fresh runprometheus deployments pause <id> | resume <id> | rm <id>

--pin V freezes the deployment on script version V (omit to track latest).

bash
prometheus deploy RxTLhAZ31… --every 6hprometheus deployments run dXf91k… -o latest.json    # fresh data, on demand (~2 min max)prometheus deployments data dXf91k… | jq '. | length'

Recipes

bash
# Build code and drop it into a projectprometheus build "all job postings on stripe.com/jobs" --json | jq -r .script > src/collect-jobs.ts
# Build once, then save + schedule that exact collectorSID=$(prometheus build "competitor pricing tiers" --json | jq -r .sessionId)prometheus scripts create --session "$SID" --every daily@08:00 --name "Pricing watch"
# An on-demand data endpoint: create without a schedule, run when neededprometheus scripts create "competitor pricing table" --no-scheduleprometheus deployments run <deploymentId> -o latest.json
# Poll a script's freshest stored dataprometheus scripts data <id> | jq '.items | length'

See also: the API reference and the MCP reference.

PreviousAPI referenceNextMCP reference