# 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](https://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

```bash
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

```bash
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`).

```bash
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).

```bash
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](./skills/prometheus/) that teaches coding
agents (Claude Code, etc.) to reach for Prometheus whenever they need web data —
instead of hand-writing scraping logic.

```bash
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`.

```bash
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](https://firecrawl.dev/prometheus).