https://github.com/ztroop/zephyr
Unix Task Scheduler
https://github.com/ztroop/zephyr
Last synced: 4 months ago
JSON representation
Unix Task Scheduler
- Host: GitHub
- URL: https://github.com/ztroop/zephyr
- Owner: ztroop
- License: mit
- Created: 2025-05-01T12:28:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-26T01:51:54.000Z (about 1 year ago)
- Last Synced: 2026-02-14T19:15:41.596Z (5 months ago)
- Language: Rust
- Size: 75.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# zephyr 💨
[](https://github.com/ztroop/zephyr/actions/workflows/build.yml)
Zephyr is a modern, lightweight task scheduler for Unix-like systems that runs as a background service. It combines the flexibility of CRON with the simplicity of interval-based scheduling, while handling system sleep and restarts gracefully. Perfect for automation tasks, backups, and periodic maintenance jobs.
## Features
- **Flexible Scheduling**: Supports both interval-based and CRON scheduling
- **Immediate Execution**: Run commands immediately on startup
- **Sleep Handling**: Automatically detects and recovers from system sleep
- **State Persistence**: Saves command history and schedules between restarts
- **Command Management**:
- Working directory and environment variable support
- Command timeout handling
- Minimum interval enforcement
- **Service Integration**: Install as a system service (systemd/launchd)
- **Cross-Platform**: Works on Linux and macOS
- **TOML Configuration**: Simple, readable configuration format
- **Detailed Logging**: Comprehensive execution and error logging
## Configuration
### Global Options
- `log_level`: Logging level (e.g., "info", "debug", "error")
- `min_interval_seconds`: Minimum time between command executions (1-3600 seconds, default: 30)
- `state_path`: Path to the state database file (default: ~/.local/state/zephyr/state.db)
- `max_immediate_executions`: Maximum number of immediate commands to execute on startup (1-100, default: 10)
### Command Options
- `name`: Unique identifier for the command
- `command`: The command to execute
- `interval_minutes`: How often to run the command (in minutes)
- `cron`: CRON expression for scheduling (e.g., "0 0 \* \* \*" for daily at midnight)
- `max_runtime_minutes`: Optional timeout for command execution
- `enabled`: Whether the command is active
- `immediate`: Whether to run the command immediately on startup
- `working_dir`: Optional working directory for the command
- `environment`: Optional environment variables for the command. Values can be either direct strings or references to existing environment variables using `$VARIABLE_NAME` syntax.
Note: You must specify either `interval_minutes` or `cron`, but not both.
Here's an example configuration using both interval and CRON scheduling:
```toml
[general]
log_level = "info"
min_interval_seconds = 30
state_path = "~/.local/state/zephyr/state.db"
max_immediate_executions = 10
[[commands]]
name = "backup"
command = "backup.sh"
interval_minutes = 60.0
max_runtime_minutes = 30
enabled = true
immediate = true
working_dir = "/backups"
environment = [
["BACKUP_DIR", "/data/backups"],
["COMPRESSION", "gzip"],
["PATH", "$PATH"]
]
[[commands]]
name = "cleanup"
command = "cleanup.sh"
cron = "0 0 * * * *" # Run daily at midnight
enabled = true
```
## Installation
```sh
git clone git@github.com:ztroop/zephyr.git && cd ./zephyr
cargo install --path .
```
## Usage
```bash
# Run with custom config file
zephyr --config /path/to/config.toml
# Run with custom state file
zephyr --state-path /path/to/state.db
# Reset state database
zephyr --reset-state
# Service management
zephyr --install-service
zephyr --uninstall-service
zephyr --start-service
zephyr --stop-service
# Show help
zephyr --help
```
#### Options
- `-c, --config `: Path to configuration file (default: ~/.config/zephyr/scheduler.toml)
- `-s, --state-path `: Path to state database file (default: ~/.local/state/zephyr/state.db)
- `-r, --reset-state`: Reset the state database, clearing all command history
- `-i, --install-service`: Install Zephyr as a system service
- `-u, --uninstall-service`: Remove Zephyr service
- `-S, --start-service`: Start the Zephyr service
- `-X, --stop-service`: Stop the Zephyr service
### Example Usage
1. Create a configuration file:
```bash
mkdir -p ~/.config/zephyr
touch ~/.config/zephyr/scheduler.toml
```
2. Edit the configuration to add your commands:
```bash
nano ~/.config/zephyr/scheduler.toml
```
3. Run Zephyr:
```bash
zephyr --config ~/.config/zephyr/scheduler.toml
```
4. Or install as a service:
```bash
zephyr --install-service
zephyr --start-service
```