iCloud Utils

This repository contains three small, independent macOS tools for Restic backups, scoped iCloud Drive materialization, and read-only Himalaya mail access:

Tool	Short command	Responsibility
icloud-backup	icback	Incremental backups of configured folders through Restic, with local integrity checks, retention safeguards, scheduling, and an independent watchdog
icloud-materialize	icmat	Metadata-only inspection or bounded iCloud materialization and complete local reads for explicitly named paths
icloud-mail	icmail	Read-only Himalaya mail access, connection diagnostics, and private per-message review tracking

The commands share source and documentation, not a runtime. The Swift materializer needs no Python, Restic, backup configuration, or scheduled job. The Python backup remains usable when the materializer is absent. Mail is an optional Python/Himalaya companion that reuses private account configuration and credential providers; neither of the other tools depends on it.

Backups use Restic's empty-password mode: anyone with the complete backup store can recover its contents. Review backup setup and its privacy boundary before creating a store.

Start here

Need	Start with
Check or materialize one explicit path	Quick start
Create a backup installation	New backup setup
Find or update an existing installation	Operations
Configure backup sources, exclusions, retention, or runtime limits	Backup configuration and examples/backup.toml
Configure, install, or use the mail companion	Mail setup, commands, and review contract
Restore without this installation	RECOVERY.txt
Diagnose a failure	Troubleshooting
Understand the design and guarantees	Architecture and design decisions
Review test coverage or release readiness	Validation
Change the project as a coding agent	AGENTS.md

Check or materialize an explicit path

If icmat is not installed, follow materializer installation first.

icmat check --json -- "$HOME/Library/Mobile Documents/com~apple~CloudDocs/example"
icmat fetch --verbose -- "$HOME/Library/Mobile Documents/com~apple~CloudDocs/example"

check inventories metadata without downloading content; fetch reads every included regular file completely. Neither result proves completed iCloud synchronization. The materializer contract explains scope, options, and result limits.

Develop and verify

Start with the source layout, then run make test from the checkout. Validation owns focused test commands, dependencies, coverage, and release limits. Keep private configuration, backup stores, archive data, machine logs, and generated build caches outside this repository.

The project is MIT licensed.