Command line

DeltaSnap bundles dsnap; deltasnap is an equivalent long-form command. Open the app once, complete onboarding, and approve the helper. When no conflicting object exists, the helper links both names into /usr/local/bin.

Verify the CLI and helper:

dsnap version

version works even when the helper is unavailable. It prints the CLI version, build commit when available, and either the helper version or helper unavailable.

Selectors

A volume resolves case-insensitively by:

• display name;
• filesystem UUID;
• mount path; or
• BSD device name, with or without /dev/.

If two volumes share a display name, use the UUID.

A snapshot operand has the form <volume>@<reference>. The reference can be:

• a full kernel snapshot name;
• a decimal XID;
• HEAD, HEAD~1, HEAD~2, and so on; or
• an unambiguous display label.

The CLI splits a compound operand on the first @, so snapshot labels cannot contain @.

List volumes, snapshots, and containers

dsnap list
dsnap list -t volume
dsnap list -t snapshot
dsnap list -t snapshot data
dsnap list -t container
dsnap list -p

The default lists volumes. Short type aliases are vol, snap, and cont. -p prints exact byte counts instead of compact 1024-based sizes. Snapshot rows show each snapshot's private size, the space referenced only by that snapshot, measured on demand and cached by the background service. Apple OS rollback snapshots remain hidden; visible third-party snapshots remain listed.

Create snapshots

Create a non-expiring manual snapshot with an optional label:

POINT=$(dsnap snapshot data@before-upgrade)

Manual snapshots do not expire by age. They are eligible for low-space pruning unless protected.

For agent runs, scripts, migrations, and other short-lived checkpoints, use --safety or -s:

PRE=$(dsnap snapshot --safety data@ai-pre-r1)
POST=$(dsnap snapshot -s data@ai-post-r1)

Safety snapshots expire after the machine-wide safety retention period (24 hours by default). The command prints a stable <volume>@<kernel-name> reference; capture it instead of assuming HEAD will continue to identify the same point.

snapshot is also available as snap.

Protect snapshots

Protection exempts a snapshot from every automatic pruner:

dsnap hold data@before-upgrade
dsnap unhold data@before-upgrade
dsnap release data@before-upgrade
dsnap holds
dsnap holds data

release is an alias for unhold. hold and unhold accept multiple snapshot operands. holds lists explicit holds and automatically protected snapshots, optionally limited to one volume.

Add and inspect tags

Each snapshot can carry one free-form tag up to 8 KiB. Plain text and JSON are both valid:

dsnap tag "$PRE" '{"agent":"codex","session":"42","phase":"pre"}'
dsnap tag "$PRE"
dsnap tags
dsnap tags data
dsnap tag --clear "$PRE"

Running tag with no value prints the current value. Setting a new value replaces the old one. Quote values that contain spaces, JSON punctuation, or begin with -.

Tags are searchable in the app. On writable movable volumes, tag metadata travels with the disk; internal-volume tags are kept in DeltaSnap's local helper state.

Create APFS volumes

create adds an APFS volume to a container; it does not create a snapshot:

dsnap create disk3/Projects
dsnap create -o type=apfsx,quota=100G,reserve=20G disk3/Projects
dsnap create -o mountpoint=/Users/me/Work disk3/Work

Supported options are:

• type=apfs|apfsx;
• quota=<size>;
• reserve=<size>; and
• mountpoint=<whitespace-free-absolute-path>.

Pass several comma-separated options after one -o, or repeat -o. Encrypted volume creation is not supported in 0.7.1.

Mount and unmount

dsnap mount data@HEAD~1
dsnap mount data@HEAD~2 data@HEAD~1
dsnap mount
dsnap unmount data@HEAD~1
dsnap unmount /Volumes/<resolved-mount>

Mounting exposes a snapshot read-only and prints its resolved path. External snapshots mount too; if one is already mounted, DeltaSnap reads from that existing mount. mount with no operand lists active DeltaSnap-managed mounts. mount and unmount accept multiple operands; unmount accepts either snapshot selectors or exact mount paths.

Visible external snapshots can be listed, mounted, indexed, compared, tagged, and destroyed deliberately, the same as DeltaSnap's own. Only Apple's com.apple.os… rollback snapshots stay out of reach.

Compare snapshots

dsnap diff data@HEAD~1 data@HEAD
dsnap diff --format=tree data@HEAD~1 data@HEAD
dsnap diff --format=zfs data@HEAD~1 data@HEAD
dsnap diff --full data@HEAD~1 data@HEAD

Both snapshots must be on the same volume. Operand order does not matter; DeltaSnap normalizes the comparison to older → newer.

Formats are:

• unified (default): path-oriented - and + lines with a summary on standard error;
• tree: changed entries nested below their ancestor folders; and
• zfs: one changed path per line with +, -, M, X, or R markers.

The normal comparison uses the persistent index and its exclusions. --full performs a one-off scan that ignores those exclusions, saves nothing to history, and can be much slower.

Destroy snapshots

dsnap destroy data@HEAD~2 data@HEAD~3
dsnap destroy --force data@HEAD~2
dsnap destroy --all-snapshots --force data

For a normal bulk request, every selector is resolved before any deletion starts. --force or -f unmounts mounted targets and bypasses individual protection.

--all-snapshots requires force and targets every visible snapshot on exactly one volume, including third-party snapshots. Hidden com.apple.os… rollback snapshots remain outside the command.

Schedules and retention

dsnap schedule list
dsnap schedule show data
dsnap schedule enable data
dsnap schedule disable data
dsnap schedule set data \
  --freq=4 --hourly=24 --daily=7 --weekly=4 --monthly=1 \
  --prune-on-low-space=on --low-bytes=30G --protect-foreign=off

schedule enable and disable control the per-volume master switch. schedule set edits retention counts and pruning values; cadence toggles themselves are configured in the app.

The 0.7.1 suggested policy enables Frequent, Hourly, and Daily with counts 4, 24, and 7. Weekly has a suggested count of 4 but starts off; Monthly starts off and can be set from 1 to 12 when enabled in the app.

--low-bytes accepts raw decimal bytes or M/MB and G/GB suffixes. Boolean flags accept on|off, true|false, yes|no, or 1|0. The low-space threshold has a 5 GB floor and a 30 GB default.

There is no age-pruning flag. Automatic snapshots no longer covered by active count rotation use fixed natural lifespans: Frequent 1 hour, Hourly 24 hours, Daily 7 days, Weekly 30 days, and Monthly 365 days. Safety snapshots use the machine-wide safety TTL. Manual snapshots are pruned automatically only under low space.

Third-party snapshots are excluded from count, lifespan, and safety-TTL pruning. The protect-foreign setting controls whether low-space pruning may consider them, and it defaults to on: DeltaSnap can now present another tool's snapshot as browsable, restorable history, so deleting one to reclaim space would be destroying that tool's restore point. Turn it off per volume if you would rather reclaim the space. Explicit holds still win.

Email notifications

dsnap email status prints the mail server settings (never the password, only whether one is stored), the delivery scope, and the delivery status: last successful send, last problem, and how many items are waiting.

dsnap email set key=value ... changes settings; unmentioned keys keep their values. Keys: enabled=on|off, scope=critical|all|everything, to=a@example.com,b@example.org, from=, host=, port=, security=tls|starttls|none, user=, and password=. Use password=- to read the password from standard input so it does not land in the shell history.

dsnap email test sends one test message with the stored settings and prints what the server said if it fails. The background service does the sending, so a configuration made from Terminal works on a Mac where the app is never opened.

Index and license status

dsnap index-mode
dsnap index-mode full
dsnap index-mode off
dsnap license status

index-mode with no argument prints the current setting. full proactively builds snapshot history; off defers indexing until a comparison requests it.

license status reports entitlement phase, masked key, licensed email when available, trial/license expiry, and offline-grace status.

Exit status and streams

Important exit codes are:

Tables, resolved identifiers, tags, and mount paths go to standard output. Diagnostics, progress spinners, index progress, and diff summaries go to standard error, which keeps command substitution usable:

PRE=$(dsnap snapshot --safety data@ai-pre-r1)