# 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.

![CI Status](https://7000pct.gitea.bloupla.net/api/status/7000pctAUTO/cron-parser-cli/pipeline)
![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

## 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)

```bash
pip install cron-parser-cli
```

### From Source

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

### Using pipx

```bash
pipx install cron-parser-cli
```

## Quick Start

```bash
# 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.

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

```bash
# 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.

```bash
# 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.

```bash
cronparse generate
```

### explain

Get human-readable description of a cron expression.

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

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

```bash
# 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.