{"content":"# aux4/cron\n\nUser-friendly cron scheduler with aux4/jobs integration.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/cron\n`\n\n## Quick Start\n\n`bash\n# Start the scheduler\naux4 cron start\n\n# Add a task that runs every 5 minutes\naux4 cron add --name cleanup --every \"5 min\" --run \"aux4 cleanup run\"\n\n# Add a daily task at 2am\naux4 cron add --name backup --every \"1 day\" --at \"02:00\" --run \"aux4 backup run\"\n\n# List all tasks\naux4 cron list\n\n# View execution history\naux4 cron history --name backup\n\n# Stop the scheduler\naux4 cron stop\n`\n\n## Commands\n\n### Start the scheduler\n\n`bash\naux4 cron start\naux4 cron start --port 9000\naux4 cron start --dir /var/data\n`\n\n### Stop the scheduler\n\n`bash\naux4 cron stop\naux4 cron stop --port 9000\n`\n\n### Add a scheduled task\n\n`bash\naux4 cron add --name cleanup --every \"5 min\" --run \"rm -rf /tmp/cache/*\"\naux4 cron add --name backup --every \"1 day\" --at \"02:00\" --run \"aux4 backup run\"\naux4 cron add --name report --every monday --at \"09:00\" --run \"aux4 report generate\"\naux4 cron add --name heartbeat --every 30s --run \"curl -s http://localhost/health\"\n\n# One-time delayed task (runs once then auto-removes)\naux4 cron add --name reminder --in \"5 min\" --run \"echo time is up\"\n\n# Limited executions (auto-removes after 3 runs)\naux4 cron add --name retry --every 10s --max 3 --run \"curl -s http://localhost/health\"\n\n# Run once at a specific time (AM/PM supported)\naux4 cron add --name alert --at \"2pm\" --run \"echo lunch time\"\n`\n\n### Remove a task\n\n`bash\naux4 cron remove --name cleanup\n`\n\n### Pause a task\n\n`bash\naux4 cron pause --name backup\n`\n\n### Resume a task\n\n`bash\naux4 cron resume --name backup\n`\n\n### List all tasks\n\n`bash\naux4 cron list\n`\n\n### View execution history\n\n`bash\naux4 cron history --name backup\naux4 cron history --name backup --limit 20\n`\n\n## Time Expressions\n\n| Expression | Type | Meaning |\n|---|---|---|\n| 10s | interval | Every 10 seconds |\n| 30s | interval | Every 30 seconds |\n| 5 min or 5min | interval | Every 5 minutes |\n| 15 min | interval | Every 15 minutes |\n| 2 hours or 2h | interval | Every 2 hours |\n| 1 day | daily | Every day (use --at for specific time, default midnight) |\n| monday | weekly | Every Monday (use --at for time) |\n| tuesday...sunday | weekly | Every specific weekday |\n| weekday | weekly | Monday through Friday |\n| weekend | weekly | Saturday and Sunday |\n| 1 month | monthly | Every month on the 1st |\n\nShort forms: 10s, 5min, 2h, 1d\nLong forms: 10 seconds, 5 minutes, 2 hours, 1 day\nSingular/plural: 1 minute = 1 min\nDay names are case-insensitive.\n\n### One-time scheduling\n\n| Flag | Description |\n|------|-------------|\n| --in \"5 min\" | Run once after a delay, then auto-remove |\n| --at \"2pm\" (without --every) | Run once at the specified time, then auto-remove |\n| --max 3 | Stop and auto-remove after N executions |\n\nTime formats for --at: HH:MM (24h), 2pm, 2:30pm, 12:00am.\n\n## Integration with aux4/jobs\n\nWhen a cron entry triggers, it executes the command via aux4 jobs run \"<command>\". This provides:\n\n- Background execution\n- Output capture (stdout/stderr)\n- Job status tracking\n- Job ID for each execution\n\nView job details with:\n\n`bash\naux4 jobs status <jobId>\naux4 jobs output <jobId>\n`\n\n## Persistence\n\n- .cron.json stores all cron entries (created in the working directory)\n- .cron-history.json` stores execution history (last 1000 entries)\n- On restart, the scheduler loads existing entries and resumes scheduling\n"}