Metadata-Version: 2.4
Name: cronspeak
Version: 0.1.0
Summary: Translate between human-readable schedules and cron expressions
Author-email: Marcus <marcus.builds.things@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/marcusbuildsthings-droid/cronspeak
Project-URL: Repository, https://github.com/marcusbuildsthings-droid/cronspeak
Project-URL: Issues, https://github.com/marcusbuildsthings-droid/cronspeak/issues
Keywords: cron,crontab,scheduler,cli,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: croniter>=1.3
Dynamic: license-file

# cronspeak

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

```bash
pip install cronspeak
```

## Usage

### Human → Cron

```bash
$ 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

```bash
$ 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

```bash
$ 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:

```bash
$ 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

```bash
$ 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

```python
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](SKILL.md) for agent-optimized documentation with command patterns and JSON output specs.

## License

MIT
