Metadata-Version: 2.4
Name: tickr-cron
Version: 1.0.4
Summary: Cron for humans - schedule tasks with natural language
Home-page: https://github.com/Bugra020/tickr
Author: Bugra020
Author-email: bugra020@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![Run Tests & Linters](https://github.com/Bugra020/scheduler-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/Bugra020/scheduler-cli/actions/workflows/tests.yml)
# Tickr

> **Cron for humans** - tickr tasks with natural language

A simple, cross-platform task scheduler that's easier to use than cron, with human-readable syntax and built-in logging.

## Features

- 📝 **Natural language scheduling** - "every 5 minutes", "every monday at 9am"
- 💾 **Persistent storage** - tasks survive restarts
- 📊 **Built-in logging** - track all executions with stdout/stderr
- 🔄 **Retry logic** - automatically retry failed tasks
- ⏱️ **Timeout support** - kill long-running tasks
- 🖥️ **Cross-platform** - works on Linux, macOS, and Windows
- 🎯 **Simple CLI** - no complex cron syntax to remember

## Quick Start

### Installation

```bash
pip install tickr-cron
```

Or with pipx (recommended):

```bash
pipx install tickr-cron
```

### Add Your First Task

```bash
# Run a backup script every day at 2am
tickr add backup-db --run "python backup.py" --when "every day at 2:00"

# Check on a service every 5 minutes
tickr add health-check --run "curl https://myapp.com/health" --when "every 5 minutes"

# Send a weekly report
tickr add weekly-report --run "./send_report.sh" --when "every monday at 9:00"
```

### Start the Daemon

```bash
# Start in background (Unix-like systems)
tickr daemon

# Or run in foreground (useful for debugging/Docker)
tickr daemon --foreground
```

### View Your Tasks

```bash
# List all tasks
tickr list

# Detailed view
tickr list --verbose

# Check execution history
tickr logs backup-db

# Check daemon status
tickr status
```

## Supported tickr Formats

### Interval-based

- `every 5 minutes` - every N minutes
- `every hour` - every N hours  
- `every 3 days` - every N days

### Time-based

- `every day at 14:30` - daily at specific time
- `every monday at 9:00` - weekly on specific day
- `every weekday at 8:00` - Monday-Friday at specific time

### Day-based

- `every monday` - every specific weekday
- `every friday` - any day of the week
- `every weekday` - Monday through Friday

## CLI Commands

### `tickr add`

Add a new scheduled task.

```bash
tickr add <task_name> --run <command> --when <schedule> [options]

Options:
  --timeout SECONDS     Kill task if runs longer than this
  --retries N           Retry N times on failure
  --retry-delay SECONDS Wait between retries (default: 60)
```

**Examples:**

```bash
# Simple task
tickr add my-task --run "echo hello" --when "every 5 minutes"

# With timeout and retries
tickr add api-check \
  --run "curl https://api.example.com" \
  --when "every hour" \
  --timeout 30 \
  --retries 3 \
  --retry-delay 120
```

### `tickr list`

Show all scheduled tasks.

```bash
tickr list [--verbose]
```

### `tickr run`

Execute a task immediately (ignores schedule).

```bash
tickr run <task_name>
```

### `tickr logs`

View execution history for a task.

```bash
tickr logs <task_name> [--limit N] [--failed-only]

Options:
  --limit N         Show last N runs (default: 10)
  --failed-only     Only show failed executions
```

### `tickr enable/disable`

Enable or disable a task without deleting it.

```bash
tickr disable <task_name>
tickr enable <task_name>
```

### `tickr remove`

Delete a task and all its execution history.

```bash
tickr remove <task_name>
```

### `tickr daemon`

Start the tickr daemon.

```bash
tickr daemon [--foreground]

Options:
  --foreground    Don't daemonize (useful for debugging/Docker)
```

### `tickr status`

Show daemon status and next scheduled task.

```bash
tickr status
```

## Advanced Usage

### Retry Failed Tasks

```bash
tickr add flaky-api \
  --run "python sync_data.py" \
  --when "every hour" \
  --retries 3 \
  --retry-delay 300
```

If the task fails, it will retry 3 times with a 5-minute delay between attempts.

### Timeout Long-Running Tasks

```bash
tickr add slow-task \
  --run "./long_process.sh" \
  --when "every day at 3am" \
  --timeout 3600
```

The task will be killed if it runs longer than 1 hour (3600 seconds).

### Run in Docker

```dockerfile
FROM python:3.11-slim

RUN pip install tickr

# Add your scheduled tasks
RUN tickr add my-task --run "python app.py" --when "every hour"

# Run daemon in foreground
CMD ["tickr", "daemon", "--foreground"]
```

## Configuration

All data is stored in `~/.tickr/`:

- `tickr.db` - SQLite database with tasks and execution history
- `daemon.pid` - PID file for the running daemon
- `daemon.log` - Daemon logs (rotated at 10MB)
