schedls/docs/systemd.md

systemd backend

schedls manages systemd timers. A timer is always paired with a oneshot service that holds the command.

Layout

Scope	Unit directory	Manager
user	~/.config/systemd/user	systemctl --user
system	/etc/systemd/system	systemctl

new --timer defaults to user scope. System scope must be requested explicitly with --system and appropriate privileges; schedls never invokes sudo for you.

Created files

For a job named backup:

# ~/.config/systemd/user/schedls-backup.service
# Managed by schedls
# Name: backup

[Unit]
Description=schedls job backup

[Service]
Type=oneshot
ExecStart="/usr/local/bin/backup" "/srv/data"

# ~/.config/systemd/user/schedls-backup.timer
# Managed by schedls
# Name: backup

[Unit]
Description=schedls job backup (timer)

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true
Unit=schedls-backup.service

[Install]
WantedBy=timers.target

The schedls- prefix and the header comments provide provenance without a database.

Argument handling

ExecStart= is not shell syntax. schedls serializes each argument with systemd's own quoting rules and always quotes arguments, so a value such as $(...), %i, $HOME or an argument beginning with - is passed literally. Use --shell to explicitly request /bin/sh -c.

Every rendered unit is validated with systemd-analyze verify before installation.

Calendar expressions

Convenience flags compile to native OnCalendar= values:

Flag	Example	Compiles to
--daily TIME	--daily 02:00	*-*-* 02:00:00
--weekdays TIME	--weekdays 08:30	Mon..Fri *-*-* 08:30:00
--weekly D TIME	--weekly sun 04:00	Sun *-*-* 04:00:00
--monthly D TIME	--monthly 1 06:00	*-*-01 06:00:00
--calendar EXPR	--calendar 'Mon..Fri 02:30'	used verbatim

--calendar may be repeated; systemd supports multiple OnCalendar= entries.

Discovery

Timers are listed with systemctl list-unit-files and list-units, then properties are read with systemctl show. OnCalendar, Persistent and the command are read from the unit fragments. The next elapse is taken from NextElapseUSecRealtime; monotonic timers have no wall-clock next run and are reported as unknown.

Logs

schedls logs NAME queries the service unit's journal via journalctl --no-pager. The job command is never re-executed.

Two options control how much is shown, both passed to journalctl:

Option	Default	Meaning
--lines N	50	number of recent entries (journalctl --lines=N)
--since TIME	none	lower bound on entry time (journalctl --since=TIME)

TIME accepts any value journalctl --since accepts, for example '2026-09-01', '2 hours ago' or '2026-09-01 10:00:00'. --since bounds the range and --lines caps how many entries within it are shown. See cli.md for the full command reference.

Lingering

User timers only run while the user's systemd manager is alive. schedls warns when lingering is disabled but never enables it.