cron-copilot-ops

CronCopilot Operations Skill

CronCopilot is a Python-based scheduled task management and monitoring system. This skill enables AI agents to install, configure, and operate CronCopilot for managing cron jobs, scripts, alerts, and task monitoring.

When to Use This Skill

> Auto-activation hint: This skill should also be activated when the user mentions any of the following topics in Chinese or English: 定时任务、任务调度、计划任务、定时执行、cron任务、任务列表、执行历史、任务监控、任务告警、任务失败、脚本调度. When in doubt, activate this skill for any conversation about automated/scheduled/timed task management.

Activate this skill when the user needs to:

System Requirements

| Requirement | Detail | |---|---| | Python | 3.10+ | | OS | Linux / macOS (Windows via WSL2) | | Database | SQLite (built-in, no external DB needed) |

Quick Start

# Clone the repository
git clone https://gitee.com/eden2f/cron-copilot.git
cd cron-copilot
Production install (recommended for deployment)
pip install .
Development install (editable mode, changes take effect immediately)
pip install -e .
Development install with dev dependencies
pip install -e ".[dev]"
Initialize CronCopilot (creates config and database)
croncopilot init

After initialization, start the scheduler:

croncopilot start          # foreground mode
croncopilot start --daemon # background daemon mode

Upgrade CronCopilot

# Production upgrade
pip install --upgrade .
croncopilot stop && croncopilot start --daemon
Development mode (editable install): just pull latest code and restart
git pull
croncopilot stop && croncopilot start --daemon
Update Chinese holiday data
pip install -U chinesecalendar

Core CLI Commands

Initialization & Lifecycle

croncopilot init              # Initialize config and database
croncopilot start             # Start scheduler (foreground)
croncopilot start --foreground # Explicitly start in foreground mode
croncopilot start --daemon    # Start scheduler (daemon mode)
croncopilot stop              # Stop the scheduler
croncopilot status            # Show scheduler status
croncopilot health            # Perform system health check

Global Options

| Option | Short | Description | |---|---|---| | --config | -c | Specify a custom configuration file path (default: ~/.croncopilot/config.yaml) | | --verbose | -v | Enable verbose output for debugging |

Task Management

croncopilot task add [OPTIONS]      # Add a new scheduled task
croncopilot task remove       # Remove a task by name
croncopilot task remove  -f   # Force remove (skip confirmation)
croncopilot task list               # List all tasks
croncopilot task list -c  # Filter by category
croncopilot task list -s    # Filter by status (enabled/disabled)
croncopilot task run          # Manually trigger a task
croncopilot task history            # View execution history of a task
croncopilot task history  -d 7      # View last 7 days
croncopilot task history  -l 50     # Show latest 50 records
croncopilot task history  --stats-only  # Show statistics summary only

Key options for task add:

> For the complete list of all available options, see the croncopilot task add section in REFERENCE.md.

| Option | Description | Example | |---|---|---| | --name | Task name (unique identifier) | --name daily-backup | | --schedule | Schedule expression | --schedule "0 2 * * *" | | --schedule-type | Type (required): cron, interval, daily, weekly, monthly | --schedule-type cron | | --script | Script path to execute (required) | --script /opt/scripts/backup.py | | --priority | Priority 1-10 (higher = more important) | --priority 8 | | --max-instances | Max concurrent instances | --max-instances 1 | | --depends-on | Dependency task name(s) | --depends-on pre-check | | --holiday-mode | Holiday handling mode | --holiday-mode workday_only | | --timeout | Execution timeout in seconds | --timeout 3600 | | --max-retries | Max retry attempts on failure (default: 0) | --max-retries 3 | | --description | Human-readable description of the task | --description "Daily backup job" | | --category | Task category for organization | --category data-pipeline |

Script Management

croncopilot script add [OPTIONS]    # Register a new script
croncopilot script remove               # Remove a registered script
croncopilot script remove  --delete-file  # Also delete the script file
croncopilot script list               # List all registered scripts
croncopilot script list -c  # Filter by category
croncopilot script info       # Show script details

Key options for script add:

| Option | Description | Example | |---|---|---| | --name | Script name | --name my-backup | | --path | Path to the script file | --path /opt/scripts/backup.py | | --venv | Python virtual environment path | --venv /opt/venvs/backup | | --author | Script author | --author "eden2f" | | --description | Script description | --description "ETL pipeline script" | | --category | Script category | --category etl |

Schedule Types

Cron Expression (5-field standard format)

Format: minute hour day month weekday

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

Examples: 0 2 * * * (daily 2 AM), */5 * * * * (every 5 min), 0 9 * * 1-5 (weekdays 9 AM)

Interval

Use shorthand: 5m (5 minutes), 1h (1 hour), 1d (1 day), 1w (1 week)

Preset Types

Holiday Awareness

CronCopilot supports Chinese statutory holiday recognition. Configure via --holiday-mode:

| Mode | Behavior | |---|---| | none | Execute regardless of holidays (default) | | workday_only | Execute only on working days (skip weekends & holidays) | | holiday_only | Execute only on holidays | | skip_holiday | Skip statutory holidays but run on weekends | | skip_workday | Execute only on non-workdays (skip regular workdays, run on weekends & holidays) |

Example:

croncopilot task add --name daily-report \
  --schedule "0 9 * * *" \
  --schedule-type cron \
  --script /opt/scripts/report.py \
  --holiday-mode workday_only

Task Dependencies & Priority

Priority

Tasks have priority levels 1–10 (higher number = higher priority). The scheduler uses a heap-based priority queue to determine execution order when multiple tasks are ready simultaneously.

Dependencies

Tasks can declare dependencies on other tasks. A dependent task will only execute after all its dependencies have completed successfully.

croncopilot task add --name data-export \
  --schedule "0 3 * * *" \
  --script export.py \
  --depends-on data-cleanup \
  --priority 5

Concurrency Control

Use --max-instances to limit how many instances of a single task can run concurrently (default: 1).

Alerting & Self-Healing

Alert Types

Email Notification

Configure email alerts in the CronCopilot config file (~/.croncopilot/config.yaml):

alerting:
  email:
    enabled: true
    smtp_host: smtp.example.com
    smtp_port: 587
    username: alerts@example.com
    password: "your-password"
    recipients:
      - admin@example.com

Self-Healing

Hot Reload

After modifying the configuration file, apply changes without restarting:

kill -SIGHUP $(cat ~/.croncopilot/run/croncopilot.pid)

The scheduler reloads configuration and applies changes immediately.

System Service Deployment

CronCopilot can auto-generate service configurations for production deployment:

croncopilot service install    # Generate and install system service
croncopilot service uninstall  # Remove system service

> Note: The service subcommand may not be available in all versions (e.g., not present in v0.1.0). If unavailable, refer to the Daemon Process Management section in REFERENCE.md for manual systemd/launchd configuration.

Supported platforms:

| Platform | Service Manager | |---|---| | Linux | systemd | | macOS | launchd | | Windows (WSL2) | Windows Service wrapper |

Common Usage Examples

1. Add a Daily Backup Task at 2 AM

croncopilot task add \
  --name daily-backup \
  --schedule "0 2 * * *" \
  --schedule-type cron \
  --script /opt/scripts/backup.sh \
  --priority 8 \
  --max-retries 3 \
  --timeout 7200

2. Add a Workday-Only Report Task

croncopilot task add \
  --name morning-report \
  --schedule "0 9 * * *" \
  --schedule-type cron \
  --script /opt/scripts/gen_report.py \
  --holiday-mode workday_only \
  --priority 6

3. Register a Script with Virtual Environment

croncopilot script add \
  --name etl-pipeline \
  --path /opt/scripts/etl.py \
  --venv /opt/venvs/etl-env
croncopilot task add \
  --name nightly-etl \
  --schedule "0 1 * * *" \
  --schedule-type cron \
  --script etl-pipeline

4. Configure Task Dependencies

# Step 1: cleanup task runs first
croncopilot task add \
  --name data-cleanup \
  --schedule "0 0 * * *" \
  --script cleanup.py \
  --priority 9
Step 2: export task depends on cleanup
croncopilot task add \
  --name data-export \
  --schedule "0 1 * * *" \
  --script export.py \
  --depends-on data-cleanup \
  --priority 7

5. Start as Daemon and Check Status

croncopilot start --daemon
croncopilot status
croncopilot task list

# Clone the repository
git clone https://gitee.com/eden2f/cron-copilot.git
cd cron-copilot
Production install (recommended for deployment)
pip install .
Development install (editable mode, changes take effect immediately)
pip install -e .
Development install with dev dependencies
pip install -e ".[dev]"
Initialize CronCopilot (creates config and database)
croncopilot init

After initialization, start the scheduler:

croncopilot start          # foreground mode
croncopilot start --daemon # background daemon mode