skdlr

Cross-platform task scheduler with native OS integration.

skdlr provides a unified interface for scheduling recurring tasks across different operating systems, using native schedulers (systemd, launchd, Windows Task Scheduler) when available, with a fallback internal scheduler.

Features

• Native OS integration: systemd (Linux), launchd (macOS), schtasks (Windows)
• Fallback internal scheduler for portable operation
• Cron-style scheduling expressions
• SQLite-based schedule storage
• CLI, TUI, and library interfaces
• MCP server for AI agent integration
• HTTP API for dashboard integration (e.g., octo)

Installation

cargo install --path crates/skdlr-cli

Or build from source:

cargo build --release

Quick Start

# Add a schedule
skdlr add backup --schedule "0 2 * * *" --command "restic backup ~"

# List schedules
skdlr list

# Enable/disable
skdlr disable backup
skdlr enable backup

# Trigger immediate run
skdlr run backup

# View execution history
skdlr logs backup

# Check status
skdlr status
skdlr backend
skdlr doctor

CLI Reference

skdlr add <name> --schedule <cron> --command <cmd>   Add a schedule
skdlr list                                            List all schedules
skdlr show <name>                                     Show schedule details
skdlr edit <name> [options]                           Update a schedule
skdlr remove <name>                                   Delete a schedule
skdlr enable <name>                                   Enable a schedule
skdlr disable <name>                                  Disable a schedule
skdlr run <name>                                      Trigger immediate run
skdlr logs <name>                                     View execution history
skdlr status                                          Overview of all schedules
skdlr next                                            Show upcoming runs
skdlr backend                                         Show active backend
skdlr doctor                                          Health check
skdlr completions <shell>                             Generate shell completions

Configuration

Config file: $XDG_CONFIG_HOME/skdlr/config.toml

# Backend (auto-detected if not set)
# backend = "systemd"  # or "launchd", "schtasks", "internal"

# Prefix for generated service/timer names
service_prefix = "skdlr"

# Default working directory
default_workdir = "~"

[internal]
# Check interval for internal scheduler (seconds)
check_interval_secs = 60

macOS (launchd) notes

Generated LaunchAgents:

• Environment/PATH: launchd runs agents with a stripped environment, so skdlr embeds EnvironmentVariables in every plist, capturing your PATH at install time (falling back to a Homebrew + system default). Commands can resolve user-installed binaries (e.g. atuin, restic). If your PATH changes, re-run skdlr enable <name> to regenerate the plist.
• Cron expressions: launchd's StartCalendarInterval cannot express cron step values, so skdlr normalizes expressions — */15 * * * * becomes an array of interval dictionaries, and * * * * * becomes StartInterval 60.
• Run history: launchd executes jobs outside skdlr, so generated plists route commands through the skdlr binary (skdlr __exec) which records each execution — scheduled or manual — in SQLite with its actual exit code. skdlr logs <name> additionally reconciles stale records against authoritative launchctl print state.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         skdlr                               │
├─────────────────────────────────────────────────────────────┤
│  CLI / TUI / MCP Server / Library                           │
├─────────────────────────────────────────────────────────────┤
│                    Backend Abstraction                      │
├───────────┬───────────┬──────────────┬──────────────────────┤
│  systemd  │  launchd  │  schtasks    │  internal            │
│  (Linux)  │  (macOS)  │  (Windows)   │  (fallback)          │
└───────────┴───────────┴──────────────┴──────────────────────┘

Crate Structure

crates/
├── skdlr-core/    # Core library (backend trait, models, storage)
├── skdlr-cli/     # Command-line interface
├── skdlr-tui/     # Terminal user interface (ratatui)
├── skdlr-mcp/     # MCP server for AI agents
└── skdlr-api/     # HTTP API server (axum)

Integration

As a Library

use skdlr_core::{Storage, Schedule, backend};

// Open storage
let storage = Storage::open(Path::new("skdlr.db"))?;

// Create and save a schedule
let schedule = Schedule::new("backup", "0 2 * * *", "restic backup ~");
storage.save_schedule(&schedule)?;

// Get backend and install
let backend = backend::create_backend(backend::BackendKind::detect(), &config);
backend.install(&schedule).await?;
backend.enable(&schedule).await?;

With octo

skdlr-api provides REST endpoints for the octo dashboard to manage schedules.

With byt

byt schedule add "catalog-refresh" --schedule "0 */6 * * *" --command "byt catalog refresh"
byt schedule list

Development

just build          # Build all crates
just test           # Run tests
just check-all      # Format, lint, test
just install-all    # Install all binaries

License

MIT