iCloud Surge Sync

One-way distribution for Surge configuration files. A primary device watches an iCloud-backed folder and publishes changes to Git. Other devices periodically pull the Git repository as read-only subscribers.

iCloud folder -> primary push device -> Git remote -> pull devices

The project uses the Git credentials already configured on each machine. It does not read or store access tokens. Use a dedicated Git repository for the mirrored Surge files. The primary push device treats tracked, visible files in the Git folder as a mirror of the iCloud folder.

Install

Node.js 18.17 or newer is required.

npm install --global @surmrf/icloud-surge-sync

Upgrade an existing installation with:

npm install --global @surmrf/icloud-surge-sync@latest
icss daemon install

daemon install is safe to run repeatedly. It rewrites the background-service file to the currently installed CLI and starts the service.

Configure a device

Interactive setup:

icss init --role push

The push role is a publisher candidate. Multiple push devices may be configured, but they coordinate through a Git lease so only one device publishes at a time.

icss init --role pull

The pull role is a read-only subscriber and does not require an iCloud folder.

Non-interactive examples:

icss init \
  --role push \
  --icloud-folder "/absolute/path/to/icloud/surge" \
  --git-folder "/absolute/path/to/local/repository" \
  --remote "[email protected]:owner/private-config.git"

icss init \
  --role pull \
  --git-folder "/absolute/path/to/local/repository" \
  --remote "[email protected]:owner/private-config.git"

--remote is only required when the local Git folder has not already been cloned.

Push devices use these lease defaults:

• deviceId: generated from hostname and username, override with --device-id
• leaseBranch: icss/lease, override with --lease-branch
• leaseTtlMs: 120000, override with --lease-ttl
• leaseRenewIntervalMs: 30000, override with --lease-renew-interval

Default configuration locations:

• macOS: ~/Library/Application Support/iCloud-Surge-Sync/config.json
• Linux: ~/.config/icloud-surge-sync/config.json

Use --config /absolute/path/config.json to override the location.

Verify and run

icss doctor
icss run

doctor validates the selected role, folders, Git repository, origin, and existing Git authentication. SSH keys or HTTPS credentials must be configured with Git before installing the background service.

Background service

macOS uses a per-user LaunchAgent. Linux uses a systemd user service.

icss daemon install
icss status
icss logs
icss daemon restart
icss daemon uninstall

Configuration and logs are retained during normal uninstall. Remove them explicitly with:

icss daemon uninstall --purge

On a headless Linux host, user lingering may need to be enabled separately so the service can start without an interactive login.

icss status prints the package version, configuration path, role, service/log paths, and Git ahead/behind/dirty state.

Multiple push devices run in active/standby mode. The active device renews a lease on the icss/lease branch. Standby push devices keep watching but do not copy, delete, commit, or push until the active lease expires or is released. After takeover, the new active device scans the whole iCloud folder before publishing so changes made while it was standby are not missed.

Pull devices use fast-forward-only pulls. If a pull device has uncommitted local changes or local commits, it skips the pull and logs the reason instead of creating a merge commit or overwriting local work.

Development

pnpm install
pnpm format
pnpm check
pnpm test
pnpm verify

Biome is the single formatter and linter for JavaScript and JSON. Use pnpm check:fix to apply formatting, import organization, and safe lint fixes together.

For backwards-compatible source execution, pnpm push and pnpm pull can use a project-root config.json based on config.json.example.