Skip to content

Watch Mode

Jump to bottom
Rob Hooper edited this page Apr 2, 2026 · 13 revisions

Watch Mode

Watch mode runs kei as a long-lived process, repeating the download cycle at a fixed interval.

Usage

# Sync every hour
kei -u my@email.address -d /photos --watch-with-interval 3600

How It Works

After completing a full download pass (enumerate → filter → download), the process sleeps for the specified number of seconds, then starts a new pass. This repeats indefinitely until stopped by a shutdown signal (Ctrl+C, SIGTERM, or SIGHUP).

Each cycle checks for changes using a stored CloudKit syncToken. If nothing changed since the last cycle, the check completes in 1-2 API calls and the cycle ends immediately. When changes are detected, only the delta is downloaded. On the first cycle (no stored token), a full enumeration is performed. See State Tracking for details.

Graceful Shutdown

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

  1. Finish any in-flight downloads (partial .part files are kept for resume)
  2. Skip remaining queued downloads
  3. Exit cleanly

If the signal arrives during the sleep interval between cycles, the sleep is interrupted and the process exits immediately. A second signal at any point force-exits the process.

Album Refresh

Albums are re-resolved at the start of each watch cycle. If you create a new album in iCloud, it will be discovered on the next cycle without restarting the daemon.

Error Tolerance

When a download cycle ends with partial failures (some files downloaded, some failed), watch mode logs a warning and continues to the next cycle instead of exiting. Transient failures are expected in long-running sessions - the next cycle retries failed assets automatically via the state database.

Only a complete failure (no files downloaded at all) causes the daemon to exit.

systemd Integration

On Linux, use --notify-systemd to integrate with systemd's service manager. kei sends:

  • READY=1 after authentication completes
  • STATUS= with cycle progress updates
  • STOPPING=1 on shutdown
  • WATCHDOG=1 heartbeats (if WatchdogSec= is configured)

Use --pid-file to write a PID file for service managers that need it.

Example systemd unit

[Unit]
Description=kei photo sync
After=network-online.target

[Service]
Type=notify
ExecStart=/usr/local/bin/kei \
    --username my@email.address \
    --directory /photos \
    --watch-with-interval 3600 \
    --notify-systemd \
    --pid-file /run/kei.pid
Restart=on-failure
WatchdogSec=7200

[Install]
WantedBy=multi-user.target

Related Flags

Commands

Getting Started

Features

Clone this wiki locally