terz

Your package's adoption, on one page, on your own box.

A run reads every registry your packages live on (npm, PyPI, crates.io, NuGet, Homebrew, Docker Hub, jsDelivr, MCP Registry, GitHub, GitLab, Forgejo, Bitbucket), appends the readings to a plain file, and rewrites one static HTML page. No account, no database, nothing to keep running. The timer is yours.

npm install -g terz-cli

mkdir adoption && cd adoption
terz init          # writes terz.config.json (inside a project, it detects your packages)
terz run           # takes a run, writes chart.html, terz.json and badge.svg

Needs Node.js 22 or newer (24 LTS recommended).

List your packages once, in terz.config.json:

{
  "name": "Acme",
  "products": [
    {
      "name": "Acme CLI",
      "slug": "acme-cli",
      "sources": {
        "crates": ["acme-cli"],
        "homebrew": ["acme"],
        "npm": ["acme-cli"],
        "pypi": ["acme-cli"],
        "github": ["acme/cli"]
      }
    }
  ]
}

Every name in it is public. Secrets (a Stripe key, a webhook URL) are never in this file; they come from the environment.

Then give the run to a timer. Once a day is right: the download APIs refresh daily, and reading them more often only spends rate limit.

0 8 * * *  cd /path/to/adoption && terz run

Commands

terz init   [dir]   detect this project's packages and write terz.config.json
terz run    [dir]   take a run and rewrite chart.html, terz.json and badge.svg
terz badge  [dir]   print the badge SVG, or generate a Markdown embed snippet
                      --markdown                print the Markdown README snippet
                      --out=<file>              write to a file instead of stdout
                      --sparkline               add a 30-day sparkline (needs a run first)

terz status [dir]   print the latest readings and deltas (local, no network)
terz watch  [dir]   keep the status view open, redrawn from local readings
                      --interval=<seconds>      redraw every N seconds (default 60)
                      --sweep-every=<minutes>   also take a run every N minutes (15 or more)
                    keys: r takes a run now, q quits
terz check  [dir]   validate terz.config.json and confirm every source answers
terz doctor [dir]   check the directory, the config and each configured registry's host
terz report [dir]   write an adoption brief in Markdown (--out=<file>)
terz export [dir]   export every reading (--format=csv|json, --out=<file>)

Flags take --flag=value or --flag value. An unknown flag or a bad value is an error (exit 2), never silently ignored.

terz init never overwrites an existing terz.config.json. It reads package.json (skipped when "private": true), Cargo.toml ([package]), pyproject.toml ([project] or [tool.poetry]) and the git remote origin (GitHub, GitLab.com, Bitbucket, Codeberg). Anything it cannot map with confidence is left out, with a note.

terz watch is local and cheap: it redraws from readings.jsonl and touches the network only when you press r or pass --sweep-every.

Colour is used only on a terminal, and never when NO_COLOR is set.

What a run leaves behind

• chart.html · the chart, one self-contained file. Serve it, or open it off disk.
• badge.svg · an SVG badge for your README: the 30-day download total, marked live, held or awaiting the same way the chart marks a reading.
• terz.json · the same chart as a document, for the Terz apps and anything else that wants the numbers. Schema: https://terz.dev.
• readings.jsonl · every reading ever taken, one JSON object per line. Append-only; your history is a file you can read with tail and back up with cp.
• alerts.json · only when alerts are on: what has already been announced.

A source that does not answer is held, not fatal: the chart keeps the last good value, dimmed, with a tag saying how long it has been held. A missing reading is never rendered as a zero; zero is a real measurement.

Alerts

Set TERZ_WEBHOOK_URL in the environment and terz run posts an alert to it (Discord and Slack webhooks both understand the payload) when:

• a package's download, install or pull count crosses an adoption milestone: 100, 500, 1k, 5k, 10k, 25k, 50k, 100k, 250k, 500k, 1M, 2.5M, 5M, 10M, 25M, 50M or 100M, counted on the organic figure the chart shows (a launch spike is not a milestone). Each milestone is announced once, and a dip and recovery never announces it again. A package seen for the first time (the first run with alerts on, or a package you just added) is recorded quietly: passing 10k is news, already having 10k is not. Stars are not milestones.
• the count of known security advisories (osv.dev) against the latest release goes up, including the first time one is seen. A count that falls is remembered, so a new advisory after a fix is announced again.

These are the same rules the hosted service runs.

The webhook URL is a secret: anyone holding it can post to your channel. It is read from the environment only, never from terz.config.json, and terz never prints it. It must be https (http://localhost is allowed for testing). Alerts go out after the run is saved, at most four at a time, each given five seconds, and a redirect is never followed. A webhook that is down or slow produces a warning on stderr, not a failed run (the exit code is still 0), and the alert is offered again on the next run. What has been announced is kept in alerts.json.

Export

Export historical readings from readings.jsonl as CSV (RFC 4180: CRLF line endings, quoted fields) or JSON:

terz export                           # CSV to stdout
terz export --format=csv --out=adoption.csv
terz export --format json --out history.json

A missing value is an empty cell; a real zero is 0.

Automate on GitHub Actions

No box to run it on? A scheduled workflow can take the daily run and commit the results back to the repository that holds your terz.config.json. The Terz source ships a complete recipe at cli/examples/github-actions.yml; the heart of it:

- name: Take a run
  env:
    TERZ_WEBHOOK_URL: ${{ secrets.TERZ_WEBHOOK_URL }}   # optional, a repository secret
  run: |
    npm install --global terz-cli@<version>             # pin the version you use
    terz run

Nothing secret is committed: the config holds public names only, and the webhook URL and any Stripe key live in repository secrets. Commit alerts.json along with the readings, or every run starts its alert history over.

Revenue, optionally

Adoption and money on one page. Set a restricted, read-only Stripe key in the environment under STRIPE_KEY_<SLUG> and give the product its Stripe account id in the config ("stripe": "acct_…"). The next run lights up revenue, subscriptions and MRR. A secret key is refused territory: use a restricted key, which starts with rk_.

License

Proprietary, source-available. You may run it and read it; you may not redistribute it or rehost it as a service. Full terms in LICENSE.

Hosted, with sign-in and history kept for you: https://app.terz.dev · Docs and the product: https://terz.dev · Support: [email protected]