Watch Mode

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.

Current Limitations

Watch mode works but has several known gaps:

• No album refresh — Albums are fetched once at startup and reused across all iterations. New albums created in iCloud won't appear until restart
• No systemd/launchd integration — No PID file, no sd_notify, no readiness signaling

These are planned improvements.

Related Flags

• --watch-with-interval