Cron Jobs

Standalone cron jobs run any shell command on a schedule — without a managed process. Unlike --cron restart schedules (which recycle a running app), cron jobs are first-class citizens of the daemon: they are persisted in ~/.pboss/cron.json, survive daemon restarts and reboots, and log every run to ~/.pboss/logs/cron/<name>.log.

pboss cron run#

Schedule a command using human-friendly syntax:

pboss cron run everyday@9:11 "bun /srv/backup.ts"

pboss cron run every-sunday@10:10 "sh /srv/cleanup.sh" --name cleanup

pboss cron run on-date@24-10-2026-23:10 "node migrate.js"

The schedule grammar#

Times use the 24-hour clock; dates are day-month-year (24-10-2026 = October 24, 2026).

Notes:

• Hour 24 means the following day: 24:30 is 00:30 the next day.
• Dates are calendar-validated (leap years included) — on-date@31-02-2026 is rejected with a clear error.
• Keywords tolerate hyphens, underscores and camelCase: on-date@, onDate@, on_date@ are the same word.
• Next-run times come from the cron-parser library, which also validates raw expressions — 6-field ones get a seconds field.
• Jobs missed while the machine or daemon was down are skipped (like classic cron); recurring jobs reschedule to their next future occurrence.
• A past time for today@… / on-date@… is rejected with a suggestion, not scheduled to never fire.

Options for cron run:

• --name, -n <name> — job name (default: derived from the command)
• --cwd <path> — working directory for the command (default: current directory)

pboss cron list#

List all scheduled jobs with their next run, run counts, and last exit status:

pboss cron list

┌────┬─────────┬─────────────┬──────────────────┬───────────────────────────┬──────┬──────┬──────────┐
│ id │ name    │ schedule    │ command          │ next run                  │ runs │ last │ status   │
├────┼─────────┼─────────────┼──────────────────┼───────────────────────────┼──────┼──────┼──────────┤
│  1 │ backup  │ everyday@9  │ bun backup.ts    │ 2026-09-07 09:00 Mon      │   14 │ ✓    │ ● online │
│  2 │ cleanup │ every-sunday│ sh cleanup.sh    │ 2026-09-13 00:00 Sun      │    3 │ ✓    │ ● online │
│  3 │ migrate │ on-date@24-10-2026-23:10 │ node migrate.js │ 2026-10-24 23:10 │  0 │ -    │ ● done   │
└────┴─────────┴─────────────┴──────────────────┴───────────────────────────┴──────┴──────┴──────────┘

One-shot jobs stay in the list with a done status after firing so you can inspect their exit code; remove them when you no longer need the record.

pboss cron next#

Preview upcoming runs without waiting for them:

pboss cron next backup --count 5

pboss cron trigger#

Run a job immediately, without waiting for its schedule (the schedule itself is unaffected):

pboss cron trigger backup

pboss cron remove#

Remove a job by id or name:

pboss cron remove backup
pboss cron remove 3

Cron jobs in ecosystem files#

Declare cron jobs alongside your apps in pboss.config.ts / ecosystem.config.{ts,json}. Starting the file registers the jobs; re-running it updates changed schedules in place (jobs are matched by name):

export default {
  crons: [
    {
      name: "backup",
      schedule: "everyday@2:00",
      command: "bun /srv/backup.ts",
    },
    {
      name: "report",
      schedule: "every-15th@10:10",
      command: "sh /srv/report.sh",
    },
    {
      // paused until you enable it later
      name: "maintenance",
      schedule: "every-sunday@5:00",
      command: "sh /srv/maintenance.sh",
      enabled: false,
    },
  ],
  apps: [
    /* … */
  ],
};

Programmatic API#

import { pboss } from "pboss";

const job = await pboss.cronAdd("everyday@9:11", "bun backup.ts", { name: "backup" });

for (const j of await pboss.cronJobs()) {
  console.log(`${j.name} — ${j.description} (runs: ${j.runCount})`);
}

await pboss.cronTrigger("backup");   // run now
await pboss.cronRemove("backup");    // remove

How execution works#

Jobs run through the system shell (/bin/sh -c on Unix, cmd /c on Windows), so pipes, redirects, and compound commands work:

pboss cron run everyday@3 "bun report.ts | mail -s 'daily report' ops@example.com"

Every run appends a header (job name, schedule, working directory), the command’s combined output, and a footer with the exit code and duration to ~/.pboss/logs/cron/<name>.log. The daemon’s scheduler sleeps until the earliest next run with a periodic watchdog rescan, so firing is precise to the second and robust against clock adjustments.