sdtab

日本語

Manage systemd user timers and services like crontab.

# Add a timer (cron syntax)
sdtab add "0 9 * * *" "uv run ./report.py"

# Add a long-running service
sdtab add "@service" "node server.js" --restart on-failure

# List all managed units
sdtab list

NAME    TYPE     SCHEDULE     COMMAND               STATUS
report  timer    0 9 * * *    uv run ./report.py    Tue 2026-03-03 09:00:00 JST
web     service  @service     node server.js        ● active
  Web Server

Features

• cron syntax — familiar * * * * * schedule format, automatically converted to systemd OnCalendar
• Long-running services — use @service to create always-on daemons with restart policies
• Resource limits — set memory, CPU, and I/O constraints per unit
• Export/Import — sdtab export dumps config to TOML, sdtab apply restores it on another machine
• Failure notifications — Slack webhook alerts when a unit fails (OnFailure= mechanism)
• Colored status — ● active (green), ● failed (red), ○ inactive (yellow) at a glance; descriptions shown as gray subtitles; auto-disabled when piped
• Zero dependencies beyond systemd — no database, no daemon, just unit files

Install

# Pre-built binary (no Rust required)
curl -L https://github.com/kok1eee/systemdtab/releases/latest/download/sdtab-x86_64-linux \
  -o ~/.local/bin/sdtab && chmod +x ~/.local/bin/sdtab

# Or via Cargo
cargo install systemdtab

# Or build from source
git clone https://github.com/kok1eee/systemdtab
cd systemdtab
cargo build --release
cp target/release/sdtab ~/.local/bin/

Requirements

• Linux with systemd 244+ (user session only — system-wide units are not supported)
• ~/.local/bin in your $PATH

Some options require newer systemd versions:

cgroups v2 is a kernel feature, not just a systemd version. Check with: test -f /sys/fs/cgroup/cgroup.controllers && echo v2 || echo v1

Amazon Linux 2 (systemd 219) is not supported — it lacks cgroups v2 and several required directives. Use Amazon Linux 2023 (systemd 252) or newer.

Note: sdtab manages user-level units only (systemctl --user). It cannot create or manage system-wide services that require root privileges. If loginctl enable-linger fails, ask your system administrator to enable it for your user.

Quick Start

# Initialize sdtab (enables linger, creates config directory)
sdtab init

# Optional: set up Slack failure notifications
sdtab init --slack-webhook "https://hooks.slack.com/services/T.../B.../xxx"

# Add a daily task at 9:00 AM
sdtab add "0 9 * * *" "./backup.sh" --name backup --memory-max 512M

# Add a service that runs continuously
sdtab add "@service" "node dist/index.js" --name web --restart on-failure --env-file .env

# Check status
sdtab list
sdtab status backup

# View logs
sdtab logs web -f

# Export config to file
sdtab export -o Sdtabfile.toml

# Apply config from file (on another machine)
sdtab apply Sdtabfile.toml --dry-run
sdtab apply Sdtabfile.toml

Commands

sdtab remove stops and disables the unit before deleting files. sdtab apply --prune only removes units with the sdtab- prefix — manually created systemd units are never touched.

sdtab edit caveat: sdtab stores metadata (original cron expression, command, etc.) as comments at the top of the .service file (# sdtab:cron=, # sdtab:command=). If you delete these comments during editing, sdtab list and sdtab export will show ? for the missing fields. The unit itself will still work — only sdtab's bookkeeping is affected.

sdtab apply updates changed units in-place (overwrite → daemon-reload) without stopping them first. Only units that actually need a restart are restarted: for services, description-only changes skip restart; for timers, service-side changes (command, env, etc.) take effect on the next trigger without restarting the timer.

sdtab init also installs a Claude Code skill file to ~/.claude/commands/sdtab.md, enabling /sdtab commands in any project.

Schedule Syntax

Standard cron expressions and convenient shortcuts:

Weekdays use English abbreviations (@mon, @tue, ..., @sun). Dates use English ordinals (@1st, @2nd, @20th, @26th). The / separator always means "at this time".

Add Options

Failure Notifications

Set up Slack notifications for when any unit fails:

sdtab init --slack-webhook "https://hooks.slack.com/services/T.../B.../xxx"

# With user mention
sdtab init --slack-webhook "https://hooks.slack.com/services/T.../B.../xxx" --slack-mention "U0700J8MN3W"

This creates a template unit sdtab-notify@.service and adds OnFailure=sdtab-notify@%n.service to all subsequently created units. When a timer or service fails, systemd triggers the notification unit, which sends a message to Slack via curl.

To opt out of notifications for a specific unit:

sdtab add "0 9 * * *" "./quiet-task.sh" --no-notify

In Sdtabfile.toml, use no_notify = true:

[timers.quiet-task]
schedule = "0 9 * * *"
command = "./quiet-task.sh"
workdir = "/home/user"
no_notify = true

Export Format

sdtab export produces a TOML file:

[timers.backup]
schedule = "0 3 * * *"
command = "./backup.sh"
workdir = "/home/user/project"
memory_max = "512M"

[services.web]
command = "node dist/index.js"
workdir = "/home/user/app"
description = "Web Server"
restart = "on-failure"
env_file = "/home/user/.env"

Use sdtab apply Sdtabfile.toml to recreate all units from this file. Add --prune to remove sdtab-managed units not in the file.

How It Works

sdtab generates standard systemd unit files under ~/.config/systemd/user/ with a sdtab- prefix. No custom daemon or database — everything is plain systemd.

~/.config/systemd/user/
├── sdtab-backup.service    # [Service] definition
├── sdtab-backup.timer      # [Timer] with OnCalendar
├── sdtab-web.service       # Long-running service
├── sdtab-notify@.service   # Failure notification template (if webhook configured)

Metadata is stored as comments in the service file (# sdtab:type=, # sdtab:cron=, etc.), so sdtab can reconstruct the original configuration without an external database.

Comparison with Alternatives

Testing

The cron parser, unit file generation, and TOML serialization are covered by 93 unit tests:

cargo test

AI Agent Support

sdtab init installs a Claude Code skill file to ~/.claude/commands/sdtab.md. After that, you can manage systemd timers from any project with natural language:

You> /sdtab run report.py every day at 9am

Claude Code interprets the intent, runs sdtab add "0 9 * * *" "uv run ./report.py" --dry-run for confirmation, then creates the timer.

The skill works globally — not just inside the sdtab repository. Once installed, any Claude Code session can create, list, and manage timers and services through /sdtab.

Also included:

• CLAUDE.md — project instructions with full command reference (auto-loaded by AI agents)
• --dry-run — preview generated unit files before committing
• --json — machine-readable output for programmatic use

sdtab list --json

[
  {"name":"backup","type":"timer","schedule":"0 3 * * *","command":"./backup.sh","status":"Mon 2026-03-02 03:00:00 JST"},
  {"name":"web","type":"service","schedule":"@service","command":"node index.js","status":"active"}
]

License

MIT