Quick start · Setup and workflow · Configuration
The CLI and desktop app use the same data repository and local configuration. If desktop build 63 is installed, keep it closed while syncing until you upgrade to a Current build containing the UI memory-growth fix.
mac-sync sync
mac-sync restore
mac-sync restore --select
mac-sync restore --list-machines
mac-sync restore --from old-mbp
mac-sync secrets init
mac-sync packages diff --from old-mbp
mac-sync packages install --from old-mbp
mac-sync editor diff --from old-mbp
mac-sync editor install --from old-mbp
mac-sync secrets list --from old-mbp
mac-sync secrets restore --from old-mbp
mac-sync manifest list
mac-sync ui
mac-sync version
mac-sync help restore
mac-sync help secrets
mac-sync list
mac-sync statusCommands:
sync: copy configured home paths into the machine snapshot, commit, and pushrun: service mode; exits successfully if the service is already runningwatch [--interval-minutes <15-44640>]: foreground FSEvents observer; debounce saves, launch one existing worker and keep timed safety/remote checks (default 60 minutes)refresh: fetch/import available snapshots without copying into source filesversions --from <machine> [--offset <n>]: list saved versions, 50 per pageverify --from <machine> [--revision <id>]: copy and hash a version in a temporary folder; no local file replacement or private-key verificationundo-restore <id> --preview|--force: inspect/recover local copies saved before replacementincoming listandincoming resolve <id> --keep-local|--use-incoming|--keep-both: review incoming conflicts; applying deletions is explicitdeliver --to <machine> --path <home-relative path> --file <local regular file>: queue an exact-path file replacement or new file for the target's next sync; repeat path/file pairs for up to 100 filesdeliveries listanddeliveries resolve <id> --apply|--keep-local: inspect the current Mac's Inbox and explicitly resolve a queued deliveryrestore: copy a machine snapshot frommac-sync-databack into$HOMEand re-clone missing GitHub repossecrets: manage encrypted secret snapshots withageand Apple Keychainpackages: manage Homebrew snapshots, diffs, and installseditor: manage VS Code extension snapshots, diffs, and installsmanifest: show configured and dynamically discovered backup pathslist: show every configured source path and repo destinationstatus: show repo, git, local status, and last-sync stateui: open the installed Mac Sync desktop app, reusing the existing app instance when it is already runningversionor--version: show the installed Mac Sync app version and build numberhelp [topic]: show general help or command-specific help
During sync, in-progress work is shown with a compact three-dot figure-eight Braille marker from mac-spinner, and completed work is printed with a tick marker. Paths that are already unchanged stay quiet.
Show the current mac-sync version SHA, local repo paths, local status files, the last completed sync, the amount of data changed by that sync, total machine snapshot storage, warning or error messages, and the captured local Git changes that caused a pre-operation pull to be skipped:
mac-sync statusSync status is local machine state and is intentionally not committed to the repo. By default it is written under:
~/Library/Application Support/mac-sync/status/
Completed real syncs and restores also write one JSON record per run under history/<machine-name>/ in that same directory. These records contain transfer metadata, typed health conditions, and credential-redacted command diagnostics; they never contain decrypted secret contents. A result is success only when all enabled work completed, partial when the usable snapshot completed but an optional subsystem was skipped, deferred when background work waits for resources or connectivity, and failed when the run stopped.
Use brew services info mac-sync for the optional Homebrew service status. The app shows its own automatic-sync schedule in Settings → Automatic sync.
Use --revision <id> to read a saved version without switching branches. Add --output <absolute empty folder> to export under home/ and absolute/ instead of replacing the original paths. Ordinary real restores save pre-restore copies and print an Undo ID. See version and transfer safety.
Restore the current machine snapshot:
mac-sync restoreWhen the current hostname has no snapshot, restore lists available snapshots from ~/github/mac-sync-data/machines/ and prompts for the source machine. Use --select to force that prompt even when the current hostname exists:
mac-sync restore --selectList available restore sources:
mac-sync restore --list-machinesShow restore help:
mac-sync help restoreRestore from another machine:
mac-sync restore --from old-mbpRestore pulls the data repository when its worktree is clean, then copies the curated paths from the selected machine's machines/<machine-name>/config/sync-paths.txt plus its persisted dynamic paths from ~/github/mac-sync-data/machines/<machine-name>/dynamic-sync-paths.txt. It also compares the selected machine's Homebrew snapshot with the local Homebrew and VS Code extension state and re-clones missing GitHub repositories from the selected machine's saved clone list into ~/github.
By default, restore copies only missing files. Existing local files in $HOME remain the golden source regardless of their timestamp. Use --force only when you have explicitly decided to replace existing local files and resolve file/directory conflicts in favour of the snapshot:
mac-sync restore --from old-mbp --forcePreview a restore without changing local files:
MAC_SYNC_DRY_RUN=1 mac-sync restore --from old-mbpIn the Mac app on the destination Mac, browse the source under Other Macs, select the files or folders, and choose Copy to This Mac. This uses the shared mac-sync-data snapshot as the transfer medium and never changes the source Mac or its archive. Before the app writes any existing local files, it asks you to keep this Mac's copy or replace it with the selected peer snapshot. Select Copy specific paths only to review the exact paths. The CLI equivalent accepts one or more --path options:
mac-sync restore --from old-mbp --path .zshrc --path .config/toolA selected-path restore intentionally skips Homebrew, VS Code, repository, and encrypted-secret restore steps; use the normal restore flow when those machine state hints are required.
When Homebrew packages differ, restore prints the manual commands needed to install missing taps, formulae, and casks or upgrade outdated packages from the synced list. It does not run those commands for you and it does not uninstall extra local packages.
When VS Code extensions differ, restore prints the manual code commands needed to reconcile the local extension set. It does not run those commands for you.
If an encrypted secrets snapshot exists for the selected machine, restore prints the mac-sync secrets list and mac-sync secrets restore commands to inspect or restore it. Normal restore never decrypts secrets automatically.
GitHub clone restore is conservative: it only uses real GitHub remotes captured from git worktrees under the configured GitHub root, strips credentials from stored remote URLs, and skips any target path that already exists.
Install the required tools:
brew install age gnu-tarInitialize this Mac's encryption identity:
mac-sync secrets initShow encrypted secrets help:
mac-sync help secretsmac-sync secrets init creates an age identity if needed, stores the private identity in Apple Keychain under mac-sync age identity, and adds only the public recipient to the shared registry:
machines/_shared/config/age-recipients.txt
The encrypted secret paths are listed in:
machines/<machine-name>/config/secret-paths.txt
By default, that file includes:
.ssh
.secrets
Once at least one recipient is configured, a normal sync writes:
~/github/mac-sync-data/machines/<machine-name>/secrets/secrets.tar.gz.age
~/github/mac-sync-data/machines/<machine-name>/secrets/included-paths.txt
~/github/mac-sync-data/machines/<machine-name>/secrets/recipients.txt
recipients.txt records the public recipients used for that archive. When the shared recipient registry changes, the next sync from a Mac that can decrypt the archive re-encrypts it for the new recipient set even when the secret files have not changed. This is how a newly trusted Mac gains access without exposing any secret values.
You can also update only the encrypted secret snapshot:
mac-sync secrets syncInspect an encrypted snapshot:
mac-sync secrets list --from old-mbpIn the Mac app, choose a machine and select View Encrypted Secrets to list the same encrypted archive's file and folder names with this Mac's Keychain identity. That view deliberately never displays secret values or writes files.
Restore encrypted secrets:
mac-sync secrets restore --from old-mbpWithout --force, restore refuses to overwrite existing local secret files. Use --force to overwrite files from the encrypted snapshot:
mac-sync secrets restore --from old-mbp --forceTest Keychain and current-machine archive access:
mac-sync secrets testEach trusted Mac should run mac-sync secrets init, which adds that Mac's public recipient to the shared registry. The Mac app offers the same action as Set Up This Mac's Access when it cannot inspect an archive. It publishes only the public recipient and never replaces an archive that this Mac cannot decrypt. After adding a new Mac, run mac-sync sync once on each source Mac to re-encrypt its current archive for the new recipient.
Before replacing an existing encrypted archive, mac-sync decrypts and compares it with the new snapshot. If that verification fails, sync stops and preserves the existing archive. A normal sync performs the Keychain recipient and archive decryption checks before changing any managed snapshot files, so an access failure cannot leave a partially updated data repository.
Homebrew package state is captured during normal mac-sync sync when brew is available. Manage it directly with:
mac-sync packages sync
mac-sync packages diff --from old-mbp
mac-sync packages install --from old-mbp
mac-sync packages install --from old-mbp --formulae-only
mac-sync packages install --from old-mbp --admin-user adm-sclarkepackages diff prints the same manual commands that restore prints. packages install runs brew bundle install from the selected machine snapshot. Use --formulae-only to skip casks, or --admin-user when cask installs need a different admin-capable account.
VS Code extension state is captured during normal mac-sync sync when the code CLI is available. Manage it directly with:
mac-sync editor sync
mac-sync editor diff --from old-mbp
mac-sync editor install --from old-mbpeditor diff prints the manual code --install-extension and code --uninstall-extension commands. editor install reconciles the local VS Code extensions to the selected machine snapshot.