cron-parser-cli/README.md

Cron Parser CLI

A powerful and user-friendly CLI tool that parses, validates, generates, and explains cron expressions in human-readable language. Perfect for developers, DevOps engineers, and system administrators who work with scheduled tasks.

Features

• Parse & Validate: Validate cron expressions and get detailed field breakdowns
• Natural Language: Convert phrases like "every Monday at 9am" to cron syntax
• Next Execution: See upcoming run times with visual timeline
• Interactive Generator: Wizard-style cron expression builder
• Human-Readable: Explain any cron expression in plain English
• Cross-Platform: Works on Linux, macOS, and Windows

Installation

From PyPI (Recommended)

pip install cron-parser-cli

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cron-parser-cli.git
cd cron-parser-cli
pip install -e ".[dev]"

Using pipx

pipx install cron-parser-cli

Quick Start

# Show help
cronparse --help

# Parse a cron expression
cronparse parse "0 9 * * *"

# Convert natural language to cron
cronparse from-text "every Monday at 9am"

# See next execution times
cronparse next "0 9 * * *"

# Generate cron interactively
cronparse generate

# Explain cron in plain English
cronparse explain "0 9 * * *"

Commands

parse

Validate and parse a cron expression, showing field breakdown.

cronparse parse "0 9 * * *"

Output:

Valid cron expression: 0 9 * * *
  minute        : 0
  hour          : 9
  day           : *
  month         : *
  day_of_week   : *

from-text

Convert natural language phrases to cron expressions.

# Various examples
cronparse from-text "every 5 minutes"
cronparse from-text "daily at 9am"
cronparse from-text "every Monday at 2:30pm"
cronparse from-text "on the 1st of every month at midnight"

next

Show next execution times for a cron expression.

# Show next 5 executions with timeline
cronparse next "0 9 * * *"

# Show 10 executions without timeline
cronparse next "0 9 * * *" --count 10 --no-timeline

generate

Interactive wizard to build cron expressions step by step.

cronparse generate

explain

Get human-readable description of a cron expression.

cronparse explain "0 9 * * *"
# Output: At 09:00 AM, every day

# Use 24-hour format
cronparse explain "0 14 * * *" --24h
# Output: At 14:00, every day

Natural Language Patterns

The tool supports various natural language patterns:

Pattern	Cron
every 5 minutes	*/5 * * * *
every hour	0 * * * *
daily at 9am	0 9 * * *
daily at 2:30pm	30 14 * * *
every Monday at 9am	0 9 * * 1
on the 1st of every month at midnight	0 0 1 * *
every 30 seconds (via cron workaround)	* * * * *

Output Formats

All commands support JSON output for scripting:

cronparse parse "0 9 * * *" --json
cronparse next "0 9 * * *" --json
cronparse explain "0 9 * * *" --json

Cron Expression Format

Standard cron format with 5 fields:

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

Development

Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
.\venv\Scripts\activate  # Windows

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linter
ruff check .

Project Structure

cron-parser-cli/
├── src/cronparse/
│   ├── __init__.py      # Package init
│   ├── cli.py           # Main CLI entry point
│   ├── parser.py        # Cron parsing & validation
│   ├── nlp.py           # Natural language conversion
│   ├── scheduler.py     # Next execution calculations
│   ├── generator.py     # Interactive wizard
│   └── describer.py     # Human-readable descriptions
├── tests/
│   ├── test_parser.py
│   ├── test_nlp.py
│   ├── test_scheduler.py
│   ├── test_generator.py
│   ├── test_cli.py
│   └── test_describer.py
├── pyproject.toml
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.