Skip to main content
This runbook covers maintainer releases of the official worldmonitor npm CLI from cli/. CLI releases are intentionally independent from desktop app releases: a cli-vX.Y.Z Git tag triggers .github/workflows/publish-cli.yml. The Python, Ruby, and Go SDKs release the same way with their own tags (py-v*, gem-v*, sdk/go/v*) — see Official SDKs → Releasing.

​
Prerequisites

  • The worldmonitor package already exists on npm.
  • npm Trusted Publishing is configured for this repository and .github/workflows/publish-cli.yml.
  • The workflow keeps permissions.id-token: write so npm can mint the short-lived OIDC credential and attach provenance.
No NPM_TOKEN repository secret is required for the current workflow. If Trusted Publishing is not configured, the publish step fails authentication until an npm package owner adds the GitHub Actions trusted publisher in npm package settings.

​
Release Steps

  1. Update cli/package.json so version is the exact version you intend to publish.
  2. Commit the version bump, and include any CLI docs or changelog updates that should ship with that version.
  3. After the release commit is on main or the intended release ref, create a tag named cli-vX.Y.Z, where X.Y.Z exactly matches cli/package.json:
  4. Push the tag:
  5. Watch the Publish CLI to npm workflow. It runs the CLI tests, verifies the tag version matches cli/package.json, and publishes with provenance.
The version-match guard is strict: cli-v0.1.3 only publishes when cli/package.json also says "version": "0.1.3".

​
Dry Run

Use the manual workflow_dispatch trigger with dry_run: true when you want to validate the package tarball without publishing. The workflow runs from cli/ and executes npm pack --dry-run. Use dry_run: false only when you intentionally want the manual workflow path to publish. Tag-triggered releases remain the normal path because the tag name is the release contract.
dry_run: false skips the version-match guard. That check is gated to tag pushes (if: startsWith(github.ref, 'refs/tags/cli-v')), so a manual workflow_dispatch publish runs without verifying cli/package.json against any tag — it publishes whatever version the package currently declares. Prefer the tag-triggered path above, which enforces the match; use manual dry_run: false only as a deliberate escape hatch after confirming the version by hand.

​
Failure Checklist

After the workflow succeeds, confirm the new version appears on npm and that npx worldmonitor --version resolves to the published version.

​
Update the Homebrew formula

The worldmonitor formula lives in Homebrew/homebrew-core. It installs the npm archive, so it needs no separate release step. Homebrew’s BrewTestBot detects the new npm version, bumps the formula, and builds the bottle. It did this for 0.2.1. After a few hours, confirm the bump with brew info worldmonitor. If the formula still shows the old version, wait until npm serves the new archive, then open the version PR yourself:
The formula test runs worldmonitor --version, wm --version, and a live anonymous worldmonitor call get_sources. A release that breaks any of these fails the Homebrew bump.