cronspeak

Translate between human-readable schedules and cron expressions. Both directions.

pip install cronspeak

Usage

Human → Cron

$ cronspeak to-cron "every 5 minutes"
*/5 * * * *

$ cronspeak to-cron "every day at 3pm"
0 15 * * *

$ cronspeak to-cron "every monday at 9am"
0 9 * * 1

$ cronspeak to-cron "every weekday at 8:30am"
30 8 * * 1-5

Cron → Human

$ cronspeak explain "*/5 * * * *"
Every 5 minutes

$ cronspeak explain "0 15 * * *"
Every day at 3:00 PM

$ cronspeak explain "30 8 * * 1-5"
Every weekday at 8:30 AM

Next Run Times

$ cronspeak next "*/15 * * * *"
Schedule: Every 15 minutes

Next 5 runs:
  2026-02-03 00:15:00 (Tuesday)
  2026-02-03 00:30:00 (Tuesday)
  2026-02-03 00:45:00 (Tuesday)
  2026-02-03 01:00:00 (Tuesday)
  2026-02-03 01:15:00 (Tuesday)

JSON Output

All commands support --json for machine-readable output:

$ cronspeak to-cron "every tuesday at 3pm" --json --show-next 3
{
  "input": "every tuesday at 3pm",
  "cron": "0 15 * * 2",
  "explanation": "Every Tuesday at 3:00 PM",
  "next_runs": [
    "2026-02-03T15:00:00",
    "2026-02-10T15:00:00",
    "2026-02-17T15:00:00"
  ]
}

Interactive Mode

$ cronspeak interactive
Cronspeak interactive mode
Enter a schedule ('every 5 minutes') or cron expression ('*/5 * * * *')
Type 'quit' to exit

> every hour
  → 0 * * * *
  Next: 2026-02-03 01:00

> 0 9 * * 1-5
  → Every weekday at 9:00 AM
  Next: 2026-02-03 09:00

Supported Patterns

Human Input

Cron Input

Standard 5-field cron expressions are supported:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Python API

from cronspeak import parse_human, explain_cron, get_next_runs

# Human → Cron
expr = parse_human("every day at 3pm")
print(expr)  # "0 15 * * *"

# Cron → Human
explanation = explain_cron("0 15 * * *")
print(explanation)  # "Every day at 3:00 PM"

# Next runs
from datetime import datetime
runs = get_next_runs("*/5 * * * *", count=3)
for run in runs:
    print(run)

For AI Agents

See SKILL.md for agent-optimized documentation with command patterns and JSON output specs.

License

MIT