194 lines
5.7 KiB
Markdown
194 lines
5.7 KiB
Markdown
[](https://git.sysmd.uk/mdaleo404/schedls/src/branch/main/LICENSE)
|
||
[](https://git.sysmd.uk/mdaleo404/schedls/releases)
|
||
[](https://git.sysmd.uk/mdaleo404/schedls/src/branch/main/.pre-commit-config.yaml)
|
||
|
||
# schedls
|
||
|
||
<div align="center">
|
||
<img src="https://git.sysmd.uk/mdaleo404/schedls/raw/branch/main/schedls.png" alt="schedls logo" width="256" />
|
||
</div>
|
||
|
||
Inspect and manage the things Linux runs later.
|
||
|
||
`schedls` is a CLI tool for inspecting and managing cron jobs and
|
||
systemd timers through one transparent interface. It is a management and
|
||
inspection layer over the operating system's native schedulers — it is not a
|
||
daemon, not a queue, and not a replacement scheduler.
|
||
|
||
```console
|
||
$ schedls
|
||
NAME SCHEDULE NEXT BACKEND SCOPE STATUS
|
||
backup daily at 02:00 tomorrow 02:00 systemd user waiting
|
||
cleanup 0 4 * * 0 — cron user active
|
||
logrotate daily — systemd system waiting
|
||
```
|
||
|
||
If you uninstall `schedls`, everything it created keeps working: a timer is an
|
||
ordinary systemd unit, and a cron job is an ordinary crontab entry.
|
||
|
||
## Install
|
||
|
||
### From the package repository
|
||
|
||
Native `.deb` and `.rpm` packages are published at
|
||
[repo.sysmd.uk/schedls](https://repo.sysmd.uk/schedls/).
|
||
|
||
#### Debian / Ubuntu
|
||
|
||
```bash
|
||
sudo mkdir -p /usr/share/keyrings
|
||
curl -fsSL https://repo.sysmd.uk/schedls/mdaleo404.gpg | sudo gpg --dearmor -o /usr/share/keyrings/schedls.gpg
|
||
|
||
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/schedls.gpg] https://repo.sysmd.uk/schedls/debian stable main" | sudo tee /etc/apt/sources.list.d/schedls.list
|
||
|
||
sudo apt update
|
||
sudo apt install schedls
|
||
```
|
||
|
||
The signing key fingerprint is
|
||
`0032C71FA6A11EF9567D4434C5C06BD4603C28B1`.
|
||
|
||
#### Fedora / RHEL
|
||
|
||
```bash
|
||
sudo rpm --import https://repo.sysmd.uk/schedls/mdaleo404.gpg
|
||
|
||
sudo tee /etc/yum.repos.d/schedls.repo > /dev/null << 'EOF'
|
||
[schedls]
|
||
name=schedls Repository
|
||
baseurl=https://repo.sysmd.uk/schedls/rpm/$basearch
|
||
enabled=1
|
||
gpgcheck=1
|
||
repo_gpgcheck=1
|
||
gpgkey=https://repo.sysmd.uk/schedls/mdaleo404.gpg
|
||
EOF
|
||
|
||
sudo dnf upgrade --refresh
|
||
sudo dnf install schedls
|
||
```
|
||
|
||
### From PyPI
|
||
|
||
```console
|
||
$ pipx install schedls
|
||
# or
|
||
$ pip install --user schedls
|
||
```
|
||
|
||
`python -m schedls` works too. Zero runtime dependencies; Python 3.11+.
|
||
|
||
## Examples
|
||
|
||
Discover everything visible to you:
|
||
|
||
```console
|
||
$ schedls
|
||
$ schedls --system
|
||
$ schedls --backend cron
|
||
```
|
||
|
||
Explore a native calendar expression without creating anything:
|
||
|
||
```console
|
||
$ schedls calendar 'Mon..Fri 02:30'
|
||
$ schedls calendar --next 10 --utc daily
|
||
```
|
||
|
||
Create a user systemd timer:
|
||
|
||
```console
|
||
$ schedls new backup --timer --daily 02:00 --persistent -- /usr/local/bin/backup /srv/data
|
||
```
|
||
|
||
Create a cron job:
|
||
|
||
```console
|
||
$ schedls new cleanup --cron --cron-expr '0 4 * * 0' -- /usr/local/bin/cleanup
|
||
```
|
||
|
||
Create a system cron drop-in as root (runs as `root` unless `--run-as` is given):
|
||
|
||
```console
|
||
$ sudo schedls new updates --cron --system --daily 03:00 -- /usr/local/bin/updates
|
||
```
|
||
|
||
Prefer to be guided? Add `-i`/`--interactive` to `new` or `edit` and any
|
||
omitted field is prompted for. Flags you do pass become pre-filled defaults:
|
||
|
||
```console
|
||
$ schedls new backup -i
|
||
$ schedls edit backup -i
|
||
```
|
||
|
||
For `new`, the wizard asks for the scope (user or system) unless `--user` or
|
||
`--system` was given; a system cron job then asks which user it should run as
|
||
(default `root`). Interactive mode is line-based (no external editor or pager),
|
||
requires a terminal, and cannot be combined with `--json`. The collected values
|
||
are shown in the usual preview and still require confirmation before anything
|
||
is written.
|
||
|
||
Inspect, change, disable, remove:
|
||
|
||
```console
|
||
$ schedls show backup
|
||
$ schedls edit backup --daily 03:00
|
||
$ schedls disable backup
|
||
$ schedls rm backup
|
||
$ schedls logs backup
|
||
```
|
||
|
||
Check what this host can do:
|
||
|
||
```console
|
||
$ schedls doctor
|
||
```
|
||
|
||
Every mutating command supports `--dry-run`, and `--yes` for scripts. Machine
|
||
output is available with `--json`.
|
||
|
||
## Design promises
|
||
|
||
`schedls` does not:
|
||
|
||
- run a background daemon;
|
||
- listen on a network port;
|
||
- make network requests;
|
||
- automatically invoke `sudo`;
|
||
- execute discovered scheduled commands;
|
||
- open an editor or pager while managing jobs;
|
||
- use a shell internally for helper commands;
|
||
- modify unmanaged schedules by default.
|
||
|
||
See [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).
|
||
|
||
## Documentation
|
||
|
||
- [docs/cli.md](docs/cli.md) — every command, option and exit code
|
||
- [docs/architecture.md](docs/architecture.md)
|
||
- [docs/security-model.md](docs/security-model.md)
|
||
- [docs/systemd.md](docs/systemd.md)
|
||
- [docs/cron.md](docs/cron.md)
|
||
|
||
## Development
|
||
|
||
```console
|
||
$ poetry install
|
||
$ poetry run pre-commit install # check hooks on every commit
|
||
$ poetry run pre-commit run --all-files
|
||
$ poetry run pytest
|
||
$ poetry run mypy
|
||
```
|
||
|
||
Formatting and linting use [ruff](https://docs.astral.sh/ruff/); security
|
||
scanning uses [Bandit](https://bandit.readthedocs.io/); both run through
|
||
[pre-commit](https://pre-commit.com/) alongside trailing-whitespace, end-of-file,
|
||
YAML and TOML checks. CI runs the same hooks on every push and pull request,
|
||
followed by a strict type check, the test matrix (Python 3.11–3.14) and a package
|
||
build. A scheduled workflow builds an SBOM and scans it with Grype.
|
||
|
||
## Support
|
||
|
||
If you find **schedls** useful, consider supporting its development:
|
||
|
||
[](https://ko-fi.com/mdaleo404)
|