cronspeak 0.1.0

Translate between human-readable schedules and cron expressions

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

Pattern	Example	Cron
Every N minutes	every 5 minutes	*/5 * * * *
Every hour	every hour	0 * * * *
Every N hours	every 2 hours	0 */2 * * *
Every day at time	every day at 3pm	0 15 * * *
At time	at 9:30am	30 9 * * *
Every weekday	every monday	0 0 * * 1
Weekday at time	every friday at 5pm	0 17 * * 5
Weekdays	every weekday at 9am	0 9 * * 1-5
Weekends	every weekend at 10am	0 10 * * 0,6
Monthly	every month on the 1st	0 0 1 * *
Shortcuts	noon, midnight	0 12 * * *, 0 0 * * *

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