Skip to content

Watch Mode

Jump to bottom
Rob Hooper edited this page Mar 8, 2026 · 13 revisions

Watch Mode

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

Usage

# Sync every hour
icloudpd-rs -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 performs a full enumeration from the API. Assets already marked as downloaded in the state database are skipped.

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. icloudpd-rs 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=icloudpd-rs photo sync
After=network-online.target

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

[Install]
WantedBy=multi-user.target

Related Flags

Commands

Getting Started

Features

Clone this wiki locally