Set Up Background Autoupdating

This guide shows you how to configure swamp to check for and install updates automatically in the background.

Prerequisites

swamp installed and on your PATH

Root-owned binaries

If your swamp binary is owned by root (e.g., installed to /usr/local/bin by an administrator), prefix all autoupdate commands with sudo:

$ sudo swamp update --setup-auto

All management commands also require sudo when a root-owned binary is detected:

$ sudo swamp update --setup-auto status
$ sudo swamp update --setup-auto disable
$ sudo swamp config set update.cadence weekly

If you run a management command without sudo, swamp prints an error explaining that sudo is required.

If you previously had a user-level scheduler installed, the system-level setup removes it automatically.

macOS

The system-level scheduler installs to /Library/LaunchDaemons/club.swamp.autoupdate.plist and logs to /var/log/swamp/ instead of ~/Library/Logs/swamp/.

Linux

The system-level scheduler installs to /etc/systemd/system/ (systemd timer) or the root crontab via sudo crontab (on systems without systemd). Logs write to /var/log/swamp/ instead of ~/.swamp/log/.

For background on why system-level and user-level schedulers exist and how switching between them works, see Background Autoupdating.

Enable autoupdate interactively

The interactive setup wizard prompts you to choose a cadence and installs the platform-native scheduler in one step:

$ swamp update --setup-auto

The wizard asks whether to check daily or weekly, then installs the scheduler and confirms:

? How often should swamp check for updates? (daily / weekly)
> daily
Autoupdate enabled and scheduler installed

Enable autoupdate non-interactively

For scripted or headless setups, use swamp config set directly:

$ swamp config set update.auto enabled

config·set: Autoupdate enabled and scheduler installed

Choose a cadence

To change the update cadence from the default (daily) to weekly:

$ swamp config set update.cadence weekly

config·set: Cadence updated to "weekly" and scheduler reinstalled

To switch back:

$ swamp config set update.cadence daily

config·set: Cadence updated to "daily"

Check autoupdate status

$ swamp update --setup-auto status

When enabled:

update: Autoupdate: enabled
update: Cadence: "weekly"
update: Scheduler installed: true
update: Last check: "2026-05-07T22:40:18.898Z" ("up_to_date")

When disabled:

update: Autoupdate is disabled. Run `swamp update --setup-auto` to enable.

Disable autoupdate

$ swamp update --setup-auto disable

update: Autoupdate disabled and scheduler removed

You can also disable via swamp config set:

$ swamp config set update.auto disabled

config·set: Autoupdate disabled and scheduler removed

View the autoupdate log

To see recent autoupdate activity:

$ cat ~/.swamp/log/autoupdate.log

You will see output like:

{"timestamp":"2026-05-07T18:27:00.474Z","versionBefore":"20260206.200442.0-sha.","versionAfter":"20260507.175426.0-sha.618a0fec","outcome":"updated"}
{"timestamp":"2026-05-07T22:05:39.415Z","versionBefore":"20260507.214509.0-sha.e2ba2941","versionAfter":null,"outcome":"up_to_date"}

Troubleshoot autoupdate

If autoupdate is not working, run swamp doctor install to diagnose the problem:

$ swamp doctor install

If the output shows UNHEALTHY, check the reported fields:

Binary owned by root — run sudo swamp update --setup-auto to set up autoupdate as a system-level scheduler (see Root-owned binaries above). Alternatively, change ownership to your user:
```
$ sudo chown $(whoami) $(which swamp)
```
Last check shows error — the Last error line describes what failed. Common causes are permission issues and network errors.
Autoupdate disabled — re-enable with swamp update --setup-auto (see above).

Refer to the Doctor reference for the full output field descriptions.