Skip to content

automations

Manage scheduled recipe runs for a project. An automation is a stored (kickoff, recipe, cron) triple; when it is due, the scheduler launches a run exactly as mini-ork run would, so the result lands in the same run directory and appears on the same board.

Templates are expanded per fire, so an automation that writes a changelog entry every Monday names a kickoff file, not a frozen copy of its contents.

Usage

mini-ork automations <subcommand> [--home <dir>] [--json]

--home selects the project home (default $MINI_ORK_HOME or ./.mini-ork). --json applies to list and scheduler status.

Subcommands

Subcommand Arguments What it does
list [--json] Show every automation and its schedule
add flags below Register a new automation
remove <id> automation id Drop it
pause <id> automation id Keep it but stop firing
resume <id> automation id Re-enable a paused automation
run <id> automation id Fire now, regardless of schedule
tick — Fire every due, enabled automation once
scheduler status [--json] Inspect the OS-level scheduler
scheduler install — Install the OS-level scheduler
scheduler uninstall — Remove it

add

mini-ork automations add \
  --id nightly-docs \
  --name "Nightly docs refresh" \
  --recipe docs \
  --schedule "17 3 * * *" \
  --kickoff-file kickoffs/docs-refresh.md
Flag Required Meaning
--id yes Stable identifier used by remove/pause/run
--name yes Human label shown by list and the board
--recipe yes Recipe to run — no classification pass
--schedule yes Five-field cron: minute hour day-of-month month day-of-week
--kickoff-file yes Kickoff expanded at fire time
--in-place no Run in the project tree instead of minting a worktree

Cron is evaluated in the machine's local time zone. Use an off-minute (3 or 17, not 0) when several projects share a host, so their runs do not contend for the same provider at the same second.

Without --in-place each fire gets its own worktree, so two fires cannot overwrite each other's edits and a failed fire leaves the project tree intact. Use --in-place only for jobs that must not branch, such as one that writes solely under the project home.

tick and the OS scheduler

mini-ork automations tick          # what the OS job calls every minute
mini-ork automations scheduler install
mini-ork automations scheduler status

tick is idempotent per schedule slot: it fires the automations that are due and skips ones already fired in that slot. scheduler install writes the host's periodic job (launchd on macOS, cron on Linux) that invokes tick; the board shows the scheduler's state under scheduler. Installing requires an absolute engine path, so the job works when no shell profile has run.

Pause before editing a kickoff you cannot afford to have half-written at fire time, then resume.

Examples

mini-ork automations list --json | jq '.[] | {id, schedule, paused}'
mini-ork automations add --id weekly-audit --name "Weekly audit" \
  --recipe bug-audit-cmgk --schedule "23 6 * * 1" \
  --kickoff-file kickoffs/weekly-audit.md
mini-ork automations run weekly-audit
mini-ork automations pause weekly-audit
mini-ork automations scheduler install

Exit codes

Code Meaning
0 Listed, added, removed, fired, or scheduler action succeeded
1 Unknown automation id, or the scheduler command failed
2 Usage error (missing required flag, malformed cron)