CLI reference

Every command, flag, and exit code.

All commands accept --database-url, falling back to $DATABASE_URL.

halyard migrate

Creates or updates the schema. Idempotent — safe to run on every deploy.

npx halyard migrate
npx halyard migrate --dry-run      # print SQL, change nothing
npx halyard migrate --schema ops   # install into a named schema

halyard status

Current queue depth and worker liveness.

npx halyard status
npx halyard status --json     # machine-readable, for monitoring

queued     142
running     10
failed       3
dead         1
workers      2  (last heartbeat 1s ago)

halyard dead-letter

npx halyard dead-letter list --limit 50
npx halyard dead-letter show --id 01J2X...
npx halyard dead-letter replay --id 01J2X...
npx halyard dead-letter replay --job send-receipt --since 24h
npx halyard dead-letter purge --older-than 30d

purge is irreversible and asks for confirmation unless --yes is passed.

halyard vacuum

Deletes completed job rows older than a retention window. Completed rows are kept by default so you can audit what ran.

npx halyard vacuum --older-than 7d

Run this on a schedule. A queue processing a million jobs a day accumulates rows quickly, and the table’s indexes degrade long before the disk fills.

Exit codes

Exit code 4 is designed for deploy pipelines: run halyard status before starting workers, and treat 4 as “run the migration first”.