Workflows: maintenance

Keeping systems up to date and healthy. For detailed command options see Utilities. For multi-host orchestration see Playbash Server Management. For periodic task scheduling see Scheduled maintenance below.

Updating software

A single command updates all package managers on the current machine:

upd

This runs apt (or dnf), snap, flatpak, brew, bun, and tmux plugins. After updating, it scans for docker-related and AppArmor upgrades and surfaces reboot recommendations.

Variant	What it does
upd	Update everything.
upd -c	Update, then clean up (runs cln afterward).
upd -r	Restart containerd + docker instead of recommending a reboot after a docker-ce upgrade.
upd -cy	Update, clean up, assume "yes" to all prompts (non-interactive, used by playbash).

Cleaning up

cln

Removes unused packages, old caches, stale Node.js versions, and dangling Docker images. Runs apt autoremove (or dnf autoremove), flatpak uninstall --unused, brew cleanup, docker system prune, and trims old Node.js minor versions.

Docker Compose stacks

Docker Compose setups live under ~/servers/. Each subdirectory contains a compose.yaml.

Command	What it does
dcm	Update the current directory's stack (pull, recreate). Reports which images changed.
dcm ~/servers	Sweep all stacks under ~/servers/: refresh what is running, start nothing (see dcm).
dcm status ~/servers	Show status of all stacks.
dcm down	Bring down the current stack; sweeps leave it down.
dcm up ~/servers	Start every stack under ~/servers/, the inverse of dcm down ~/servers; a stack with .dcm-skip stays out.
dcm prune	Prune unused Docker images globally.
dcms	Shortcut for dcm ~/servers. Used by playbash-daily and playbash-weekly.
lzd	Open lazydocker for interactive container management.

After pulling, dcm compares image digests and reports which services updated vs unchanged. After up -d, it shows a compact per-service status. On Linux, if Docker fails with an AppArmor error, dcm automatically runs sudo aa-remove-unknown and retries.

Scheduled maintenance

Daily and weekly maintenance runs automatically on always-on machines (servers, home-lab hosts). Each managed host runs its own timer — no dependence on an operator machine being up.

Setting up timers

Use setup-periodic to create systemd timers (Linux) or launchd system daemons (macOS):

setup-periodic add daily "4:00 mo-sa" "playbash run @self daily --report"
setup-periodic add weekly "4:00 su" "playbash run @self weekly --report"

@self resolves to the local hostname and runs the playbook locally (no SSH). --report produces a plain-text summary of actionable events — the notification wrapper emails it if anything needs attention. See setup-periodic for the full schedule syntax.

Prerequisites: msmtp must be installed and configured for email notifications. setup-periodic checks for sendmail and refuses to install a task if it's missing. See Msmtp for install, configuration, testing, and troubleshooting.

Fleet-wide setup

Set up all managed Linux hosts at once:

playbash exec all -- setup-periodic add daily "4:00 mo-sa" "playbash run @self daily --report"
playbash exec all -- setup-periodic add weekly "4:00 su" "playbash run @self weekly --report"

On macOS hosts, setup-periodic needs sudo for system daemons. Set up macOS hosts individually via SSH.

Managing timers

setup-periodic list                # show active periodic tasks
setup-periodic remove daily        # remove a task

On Linux: systemctl --user list-timers for detailed status.

Hosts without chezmoi

Hosts without chezmoi (no installed playbooks, no local timers) can be maintained via operator fan-out over a group of them:

setup-periodic add daily "4:00 mo-sa" "playbash push unmanaged-hosts daily-script --report"

This runs on the operator machine and pushes the playbook to the targets. Requires the operator machine to be up at run time.

How notifications work

• Clean run (all ok, no actionable events): silent — no email.
• Failure or actionable events (reboot, stuck, errors): the notification wrapper emails a plain-text summary.

Three notification paths depending on the task type:

Task type	Linux (systemd)	macOS (launchd)
Playbash	notify-playbash wrapper	notify-playbash wrapper
Generic script	OnFailure=email-notify@%n.service	notify-on-failure wrapper

Running playbooks directly

Running playbash-daily directly (instead of playbash run @self daily) is possible but loses: --report notification summary, stuck-process detection, sidecar event collection, and log capture. For scheduled tasks, always use the playbash run form.

Multi-host ad-hoc runs

For one-off runs from an operator machine (not scheduled):

playbash run all daily    # chezmoi update, dcms, upd -ry
playbash run all weekly   # chezmoi update, dcms, upd -cry

Each host produces a structured summary (reboots needed, warnings, actions taken). See Playbash Server Management for inventory setup and log viewing.

Inspecting the system

Quick aliases for common diagnostic tasks:

Command	What it shows
top (aliased to htop)	Interactive process viewer.
psg PATTERN	Search running processes by name.
oports	List open listening ports.
duf	Disk usage overview (local and FUSE mounts).
du (no args, aliased to ncdu)	Interactive disk usage browser.
free	Memory usage in megabytes.
env	Environment variables, sorted.
path	Print $PATH entries, one per line.

Which monitoring tool when?

Several system monitors are installed — each has a different strength:

Tool	Best for
htop (aliased as top)	Day-to-day process inspection — fast, familiar, lightweight.
btop	Richer dashboard with CPU/memory/disk/network graphs. Good for at-a-glance health checks.
btm (bottom)	Detailed per-process resource history, customizable widgets, vim-like keys.

For disk usage: duf gives a one-line-per-filesystem overview; ncdu (aliased as du with no args) lets you drill into directories interactively.

For network monitoring: bandwhich shows per-process bandwidth usage in real time; bmon shows interface-level throughput.