Watch Mode

Watch Mode

Watch mode runs kei as a long-lived process and repeats the sync cycle at a fixed interval.

Usage

[watch]
interval = 3600

Then run:

kei sync

For service and Docker deployments, prefer kei service run. If no config sets [watch].interval, service run falls back to once per day, 86400 seconds.

How it works

After a download pass, kei sleeps for the configured number of seconds, then starts another pass. It repeats until stopped.

Each cycle checks for changes using stored CloudKit sync tokens. If nothing changed, the check usually completes in 1-2 API calls. On the first cycle, or after sync tokens are reset, kei performs a full enumeration.

The minimum interval is 60 seconds. Short intervals risk Apple rate limiting.

Before starting a new cycle after idle sleep, kei reacquires the per-account session lock. If it cannot reacquire the lock, watch mode stops instead of starting another sync without ownership of the account session.

The /changes/database precheck is conservative. If Apple returns an empty complete page, kei may skip that wakeup, but it does not advance the database-level sync token from that empty response.

Graceful shutdown

Ctrl+C, SIGTERM, or SIGHUP during a cycle will:

1. Finish in-flight downloads when possible.
2. Keep partial .kei-tmp files for resume.
3. Skip queued downloads.
4. Persist state and exit.

A second signal force-exits.

Periodic reconcile

[watch].reconcile_every_n_cycles = N runs a read-only reconcile check every N watch cycles. It catches files deleted from the download directory between syncs. Missing files are marked failed so the next sync re-downloads them.

[watch]
interval = 3600
reconcile_every_n_cycles = 24

0 or an unset key disables the periodic check.

systemd integration

kei install writes service files that run kei service run. On Linux, kei uses systemd notification support from the generated unit. If you run your own unit, set the durable settings in TOML:

[Service]
Type=notify
ExecStart=/usr/local/bin/kei service run --config /etc/kei/config.toml
Restart=on-failure
WatchdogSec=7200

[watch]
interval = 3600
notify_systemd = true
pid_file = "/run/kei.pid"

Related

• Service
• Configuration
• Docker