crontab Explainer — turn `0 9 * * 1-5` into "Monday to Friday, 09:00"

Cron expressions are hard to read by design — and the ones that need explaining are real schedules

The 5-field crontab format is compact to the point of opacity. 0 3 */2 * 1-5 is not immediately readable even for experienced developers — is the */2 the day or the hour? The field order must be memorised. That readability gap is what drives people to paste cron expressions into explanation tools, and the expressions they paste are almost always from a production crontab, a CI workflow, or a Kubernetes manifest.

Production cron schedules describe a system’s operational rhythm: when backups run, when ETL jobs fire, when database maintenance windows open. A cron expression from a production environment is a piece of that system’s internal configuration, and it belongs in that server log about as much as a database schema does.

Internal automation schedules should not travel to external services

GitHub Actions workflows in private repositories, Kubernetes spec.schedule values, and Vercel cron configurations describe internal automation logic. Pasting those expressions to an online explainer sends an extract of that internal configuration to a third-party server, where it lands in an access log. Even if the operator is trustworthy and deletes logs promptly, the risk materialises at the moment of the HTTP request.

Generating a human-readable description of a cron expression requires only string parsing — determining which field is which, expanding range and step notation, mapping weekday and month names. No network round trip is involved in the computation.

A self-contained parser generates descriptions locally

This tool uses a hand-written parser rather than a library dependency. It handles POSIX 5-field, Spring/Quartz/GitLab 6-field (with a leading seconds field), and Quartz 7-field formats. Aliases (@daily, @hourly, @weekly, @monthly, @yearly, @annually, @midnight) are expanded to their canonical 5-field equivalents. The parser recognises *, ,, -, / special characters, named tokens (MON–SAT, JAN–DEC), and the 1-5 → ‘weekdays’ collation. @reboot is rejected intentionally — it is not a recurring schedule.

The description is assembled from the parsed field values entirely in browser memory. Open DevTools Network while typing a cron expression: no requests fire. The field breakdown table is generated the same way.

Using crontab-explain and cron-next together

crontab-explain answers ‘what does this expression mean?’ in plain language; cron-next answers ‘when does this fire next?’ with exact timestamps. Opening both tools in adjacent tabs makes it possible to fully debug any cron schedule without pasting it anywhere outside the browser. Before committing a schedule change to a production config or CI workflow, running the before and after expressions through both tools takes seconds and avoids the class of mistake where the expression looks right but fires at the wrong frequency.

How the in-house parser decomposes each field

Cron fields have a structured grammar that the parser handles via regular expressions and a small recursive descent. The atomic forms are: integer (5), range (1-5), step (*/15 or 1-30/2), list (0,15,30,45), wildcard (*), named token (MON, JAN), and alias (@daily). Lists can contain ranges, steps, and named tokens recursively — 0,5-10,*/30,MON must decompose correctly — so each list element is parsed independently and the field’s meaning is the union of the element meanings.

Description synthesis composes a sentence by walking the field results in display order. For 0 9 * * 1-5, the parser produces ‘minute: 0’, ‘hour: 9’, ‘day-of-month: *’, ‘month: *’, ‘day-of-week: 1-5 (Mon-Fri)’, then a description builder assembles ‘Monday to Friday, 09:00’ by choosing the most natural phrasing. Combinations of range, step, list, and named token expand combinatorially, so each field’s description function is its own unit that produces a stable phrase the higher-level builder can splice in.

Crontab file conventions beyond the schedule expression

A real crontab -e file carries more than schedules. Environment variable assignments (SHELL=/bin/bash, PATH=/usr/local/bin:/usr/bin:/bin, MAILTO=admin@example.com) at the top apply to every job below. MAILTO="" suppresses the default behaviour of emailing job output to the user — forgetting to set this is the classic source of post-deploy ‘why is cron flooding my inbox?’ incidents.

Vixie cron treats lines starting with # as comments but does not allow inline # inside a schedule expression (which differs from Quartz’s # special character). The % character has a peculiar convention: in the command portion after the schedule, the first % separates the command from stdin, and subsequent %s become newlines (echo Hello %World runs echo Hello with World on stdin). To use a literal percent sign, escape it with \% — which is exactly why date +%Y%m%d does not work as a date format inside crontabs unless properly escaped. This tool explains the schedule expression itself; these surrounding crontab conventions are worth checking when debugging a job that is parsing correctly but behaving unexpectedly. To decode the strftime tokens that appear after the schedule, date-format-pattern lists the full strftime / dayjs cheatsheet, and timezone-info shows how the same firing instant lands in Asia/Tokyo, UTC, or any IANA zone that the production environment uses.