prometheus CLI

A thin command-line wrapper over a running Prometheus instance's /prometheus/api/v1 surface — by default the hosted one at firecrawl.dev/prometheus. Ask Prometheus for verified, runnable Firecrawl code, manage self-healing, parameterized scripts — run them on demand or on schedules — or search and share collectors on the marketplace, without touching the web UI.

It has zero dependencies (Node ≥ 18, uses global fetch) and never embeds the agent; it just calls your instance.

Setup

npm i -g @firecrawl/prometheus-cli

prometheus login     # opens the browser: connect your Firecrawl account (OAuth)
prometheus build "top 5 Hacker News stories with title, url, points"

login saves a Prometheus API token to ~/.prometheus/config.json; prometheus whoami shows the connected team and prometheus logout forgets the token. For CI/headless use, mint a token in the web app's Settings and set PROMETHEUS_TOKEN (overrides the config file). PROMETHEUS_URL defaults to https://firecrawl.dev; use prometheus login --url http://localhost:3000 for a local instance.

Ask for code

prometheus build "top 5 Hacker News stories with title, url, points"
#   → writes ./script.ts + ./sample.json, prints how it works

prometheus build "latest stable npm version of react" --json | jq -r .script > scraper.ts
#   → agent-friendly: emits the raw JSON contract for piping

build returns a verified Firecrawl-SDK script.ts (run with tsx script.ts, needs FIRECRAWL_API_KEY) plus a sample of the data it produced. When stdout is piped or --json is passed, it prints the JSON response instead of writing files.

Options: --schema f.json (enforce an output shape), --url URL (repeatable starting points), -o DIR (where to write artifacts), --model provider:id.

Scripts — the collector, on demand or scheduled

A script is a versioned collector that self-heals when the target site changes — each heal appends a new version. Scripts can declare parameters (CLI flags the script parses, like --city); pass them per run with --param, or bind fixed values to a schedule. Without a schedule a script is an on-demand API endpoint (prometheus run / POST /api/v1/scripts/{id}/run).

prometheus scripts create "OpenAI blog post titles + urls" --every daily@09:00 --name "OpenAI blog"
prometheus scripts create "..." --session build-abc123   # save a previous build (+ schedule with --every)
prometheus scripts create "weather by city, --city flag" --name "Weather"   # parameterized, on-demand only
prometheus scripts ls                                    # scripts with their nested schedules
prometheus scripts show <id> -o script.ts                # details (+ write the latest version locally)
prometheus scripts data <id> -o latest.json              # latest collected dataset, no fresh run
prometheus scripts heal <id>                             # fix a broken script now
prometheus scripts pin <id> <version|latest>             # freeze runs on a version
prometheus scripts fork <id>                             # stop tracking a marketplace listing
prometheus scripts rm <id>                               # archives its schedules too

prometheus run <scriptId> --param city=Paris -o fresh.json   # fresh data, synchronously

Parameters: --param key=value, repeatable (repeat a key for array params). The server validates against the script's declared interface and rejects unknown or missing-required params with a per-key error.

Self-heal (--heal): off · repair · rebuild · repair_then_rebuild (default). When a run fails, Prometheus re-derives a working collector and appends it as a new version (same parameter interface) — every track-latest schedule picks it up.

Schedules — recurring runs with bound params

A schedule is a cron plus fixed parameter values on a script. One script can have many schedules (e.g. one per city).

prometheus schedules add <scriptId> --every 6h --param city=Paris --webhook https://example.com/hook
prometheus schedules ls                          # every schedule, across scripts
prometheus schedules data <sid> -o latest.json   # the schedule's coherent feed
prometheus schedules pause <sid> | resume <sid> | rm <sid>
prometheus schedules webhook <sid> <url|off>     # set/clear the run webhook

Cadence: hourly · 30m · 6h · daily · daily@14:00 · weekly · monday@09:00 · any raw cron ("0 9 * * 1"). Times are UTC.

Webhooks: --webhook URL gets a signed POST after every scheduled run (success or failure, full dataset inline). Verify X-Prometheus-Signature (t=<unix>,v1=hmac-sha256(secret, "<t>.<body>")) with the signing secret shown once at creation.

Install the Agent Skill

The package bundles an Agent Skill that teaches coding agents (Claude Code, etc.) to reach for Prometheus whenever they need web data — instead of hand-writing scraping logic.

prometheus skills install                 # → ~/.claude/skills + ~/.agents/skills (user-level)
prometheus skills install --dir .claude/skills   # → just this project

No login needed. The skill invokes this CLI when installed (falls back to curl against the API otherwise).

Marketplace

Reuse a collector someone already published — or share yours. search and show are public (no login); everything else needs prometheus login. marketplace is also available as market / mp.

prometheus marketplace search "hacker news"          # find published collectors
prometheus marketplace show <id> -o script.ts        # inspect; write the script locally
prometheus marketplace deploy <id> --subscribe       # runs the listing's current version, platform-maintained
prometheus marketplace deploy <id> --fork            # independent copy with your own self-heal
prometheus marketplace publish <scriptId> --handle me  # share a script (runs the sterility gate)
prometheus marketplace unpublish <id>
prometheus marketplace me                            # your publisher profile + listings

Subscribe vs fork: --subscribe keeps your copy synced to the listing's latest approved version and the platform maintains it (self-heal off); --fork is an independent script you own and self-heal. Both accept --name and --every (+ --param/--webhook) to schedule on your own terms in the same call. First publish needs --handle — your public, permanent publisher handle.

Add --json to any command for machine-readable output (also the default when stdout is piped), and --help for that command's flags and examples. Flags are validated per command — a typo'd flag is a hard error with a suggestion, never silently ignored. Set PROMETHEUS_DEBUG=1 to dump the full error payload on failures. The same /prometheus/api/v1 contract is available over plain HTTP, via the MCP server, and in the web app.