Docs · Sheet 02 of 05

Job files

Each Job is one TOML file in ~/.config/cuckoo/. The app writes the same files you can write by hand, so use whichever you like.

Example

A Job that runs twice a day, with a timeout and two variables. It sends no notifications.

homebrew-outdated.toml

1# Lists the formulae with a newer version.2name = "Homebrew outdated"3command = '''4brew update --quiet5brew outdated --verbose6'''7at = ["09:00", "18:00"]8timeout = 109notify = "never"1011[environment]12HOMEBREW_NO_AUTO_UPDATE = "1"13HOMEBREW_NO_ENV_HINTS = "1"

A Command on several lines goes between '''.
Comments start with #.

Keys

name, command, and one of every or at are required. Any other key, or a value of the wrong type, makes the file invalid.

Key	Type	Meaning
`name`	string	The name the app shows. Not blank.
`command`	string	Runs in your login shell. Can span several lines.
`directory`	string	Where the Command runs. Default `"~"`.
`every`	integer	Minutes between Runs, at least 1. Not with `at`.
`at`	array	Times of day, `"HH:MM"`, at least one. Not with `every`.
`timeout`	integer	Minutes, at least 1. Default: no timeout.
`notify`	string	`"never"`, `"stateChanges"` or `"everyRun"`. Default `"stateChanges"`.
`channels`	array	Any of `"mac"`, `"ntfy"`, `"bellnod"`. Default `["mac"]`.
`[environment]`	table	Variables for the Command, as strings on one line. Must come last.

Schedules

Interval. every = 15 runs every 15 minutes, on a fixed grid. Missed times are skipped, and the Job waits for the next one.
Fixed times. at = ["09:00", "18:00"] runs every day at those times, in the Mac's time zone. If the Mac was asleep, the latest missed time runs once when it wakes, marked late (due 09:00).
A time that doesn't exist on a daylight saving day runs at the first valid moment after it.
A changed Schedule counts from when the app applies it. Past times are not caught up.

The folder

Each *.toml file at the top of ~/.config/cuckoo/ is a Job. Other files and subfolders are ignored.
The file name is the Job's identity. Change name and the Job keeps its history.
Rename the file and it becomes a new Job: the old one is deleted, with its Runs. Delete the file and the Job goes, with its Runs and their logs.
The app applies changes while it is open, about half a second after you save. While it is closed, the Jobs keep running the version applied last.
Saving in the app's editor rewrites the whole file, so comments are lost.

The app writes a README.md in the folder on every launch, for people and AI agents. Your edits to it are undone.

Invalid files

A mistake in a file doesn't stop the Job. It keeps running its last valid version, and a .error file appears beside it, with one problem per line:

back-up-photos.error

1line 7: unknown key "timout"

Fix the file and the .error file is removed. A new file that was never valid makes no Job.

cuckoo check

Check a file before the app reads it. cuckoo check prints ok, or one line per problem, and exits 1 when a file is invalid. It changes nothing.

$ cuckoo check back-up-photos.toml
back-up-photos.toml:7: unknown key "timout"
$ cuckoo check back-up-photos.toml
ok

With several files, each gets its own line: disk-space.toml: ok. More in CLI.

CuckooDocs 02Job filesJonathan Fontes - Developer