Jobs command#

Usage:
  zyn jobs [command]

Commands:
  completed           list successful jobs
  discard             discard an unleased pending job
  failed              list failed jobs
  list                list registered jobs
  prune               delete expired terminal jobs
  recurring           list recurring job schedules
  retry               retry a failed or discarded job
  status [--details]  show queue counts and eligibility
  work                run the development worker in the foreground

Run the development worker, inspect queues, or manage individual jobs.

Example:
  zyn jobs status

Documentation: zyn docs cli/jobs

Local job commands use the development database. Bare zyn jobs shows help without project setup or service startup; use zyn jobs COMMAND --help for options. Production operations are separate: see Production commands.

Run and list jobs#

zyn jobs work        # Build and run the worker in the foreground
zyn jobs list        # Registered durable job names
zyn jobs recurring   # Schedule names, cron expressions, and target jobs

work uses development credentials and worker settings from zyn.zon. Stop it with the normal interruption or termination signal; it stops claiming jobs and waits for active handlers. A missing or outdated queue schema requires zyn db migrate; a newer unsupported schema is rejected. An empty direct registry reports NoJobsRegistered before compilation.

list and recurring do not start PostgreSQL or a worker. Direct registries are read without compilation; composed declarations are compiled. Names appear in registry order; recurring rows are tab-separated. Invalid direct source syntax and cron declarations report a location and excerpt.

Inspect the queue#

Command	Result
`zyn jobs status`	Pending, running, completed, failed, and discarded counts
`zyn jobs status --queue mailers --details`	Queue counts plus eligibility and expired-lease details
`zyn jobs failed --queue mailers --limit 20`	Newest failures: UUID, job, queue, attempts, error
`zyn jobs completed --limit 20`	Newest completions: UUID, job, queue, attempts, UTC completion time

Queue names use strict snake_case. Failure and completion lists default to 20 rows; --limit accepts 1–1000. Inspection never reads job arguments.

Only an unexpired lease counts as running. Scheduled work, retries, and expired leases are pending; persisted names remain counted even without a registration. --details adds ready and scheduled counts, expired leases, oldest ready age in milliseconds, and next eligibility as Unix microseconds (none if unavailable).

Retry, discard, and prune#

zyn jobs retry 0199a1c4-62c8-7d11-8c1a-6e61498e74b1
zyn jobs discard 0199a22d-654b-7e0f-bc92-3dc1a8446916
zyn jobs prune --limit 1000

Retry accepts only failed or discarded jobs. It resets attempts, clears terminal timestamps, error and lease state, makes the job immediately eligible, and notifies workers. Success prints retried ID.

Discard accepts unleased pending or retrying jobs, not running handlers. It prints discarded ID. Both updates refuse incompatible states and cannot overwrite concurrent worker claims or terminal transitions.

Prune deletes one bounded batch beyond configured retention: successful jobs default to 7 days, failed and discarded jobs to 30. Zero retention makes rows eligible for the next cleanup. --limit defaults to 1000 and accepts 1–10000; success prints pruned COUNT jobs. Repeat to continue cleanup.

Queue commands stop PostgreSQL only if they started it. They never modify production. For worker lifecycle, automatic pruning, log fields, and JSON status, see Background jobs.