jackson2w/claude-code-skills / immich-sdcard-sync-prune
immich-sdcard-sync-prune
UnverifiedThis skill should be used when building or debugging a macOS launchd automation that uploads a camera SD card's contents to Immich on insert (via @immich/cli), or when building a workflow to prune Immich assets that were deleted from their source card/folder after import. Covers the Immich CLI's non-obvious API key permission requirements (album.create vs albumAsset.create, the "Found 0 new files" scoped-key bug), launchd's StartOnMount trigger and its missing-Homebrew-PATH gotcha, parsing `immich upload -j` JSON output, the Immich bulk-delete (trash vs permanent) endpoint, and — critically — why a delete/prune workflow across multiple source cards feeding one album must scope its diff by a per-source manifest rather than diffing the whole album, or a second card mounted alone will make every surviving photo from the first card look deletable. Trigger phrases include "sd card to immich", "immich cli upload", "@immich/cli permissions", "albumAsset.create", "Found 0 new files and 0 duplicates", "launchd StartOnMount", "immich upload -j json output", "immich bulk delete trash", "DELETE /api/assets force", "prune immich assets deleted from card", "multiple sd cards same immich album".
Immich SD card auto-sync + safe prune
Pattern for automatically uploading a camera's SD card to Immich when it's inserted on a Mac, plus
a companion tool to safely prune Immich assets after the user deletes their local originals. Built
for a Canon SD card reader on macOS; the mechanics generalize to any camera/reader that mounts as a
normal volume with a DCIM folder.
Architecture
immich uploadvia@immich/cli(npm install -g @immich/cli) — notimmich-go, not the deprecated Docker-based CLI. Auth viaimmich login-key <server-url> <api-key>, which writes~/.config/immich/auth.yml. That file is created world-readable by the CLI — immich#6911 —chmod 600it immediately.- A macOS
launchdLaunchAgent withStartOnMountfires the sync script on any volume mount. The script itself filters for volumes with a top-levelDCIMfolder rather than matching a specific volume name/label — camera-formatted cards often mount with a generic name likeUntitled, and the name isn't stable across reformats anyway. - Dedup two different ways for two different purposes:
- A
synced.logstate file keyed by Volume UUID (diskutil info "$vol" | grep "Volume UUID") stops the same already-fully-synced card from re-triggering a full re-upload on every incidental/Volumeschange while it sits mounted. - Immich's own upload does checksum-based dedup server-side — re-running
uploadagainst a partially-imported card is always safe and cheap (reportsduplicates, doesn't re-transfer).
- A
The permission set — and its sharp edges
Minimum working set for upload -r -A <album>: asset.read, asset.upload, album.read,
album.create, user.read. Two things aren't obvious and aren't documented together anywhere:
- A too-narrow key doesn't error — it silently no-ops. immich#21456
and immich#22543: a scoped key can make the
CLI report
Found 0 new files and 0 duplicatesinstead of uploading, with no error. If that happens, it's a permissions problem, not a "nothing to upload" result — don't reach for--skip-hashas a workaround, since that disables the checksum dedup that makes the whole workflow safe to re-run. Widen the key's scope instead. - Adding an asset to an album needs
albumAsset.create— a separate permission fromalbum.create. Creating the album and uploading the asset both succeed with justalbum.create; the CLI then throws403: Missing required permission: albumAsset.createwhen it tries to link the two. Not mentioned in Immich's own docs as of this writing — found by running a real (non-dry-run) upload and reading the actual error, which--dry-runalone won't surface since dry-run doesn't exercise the album-link call. - The CLI matches albums by exact name string. If a human renames the album in the Immich UI after the script has been using a different name, the next sync creates a new, separate album instead of finding the renamed one. Keep the album name in the script and the album's actual name in Immich in sync deliberately.
launchd's PATH doesn't include Homebrew
launchd's default environment is PATH=/usr/bin:/bin:/usr/sbin:/sbin — no /opt/homebrew/bin.
Since immich is a Node shebang script (#!/usr/bin/env node), a script invoked via StartOnMount
fails with env: node: No such file or directory even though the same command works fine typed
into a normal Terminal (which inherits your shell's PATH). Fix: export PATH="/opt/homebrew/bin:$PATH"
explicitly at the top of any script launchd will run, and hardcode the binary's absolute path
(/opt/homebrew/bin/immich) rather than relying on which/bare immich resolving.
<key>StartOnMount</key>
<true/>
is the whole trigger — no volume-name filtering at the launchd level, no WatchPaths needed. Load
with launchctl bootstrap gui/$(id -u) <path-to-plist>. Test the whole trigger chain without a
real card using a disk image: hdiutil create -volname TEST -srcfolder <dir-with-DCIM> -format UDZO test.dmg && hdiutil attach test.dmg — this fires StartOnMount for real, end to end.
Building a manifest from upload -j
immich upload -r -j -A "<album>" <path> prints normal progress text to stdout, then a single JSON
object, then more status lines — the JSON is sandwiched in the middle, not cleanly at the end. Parse
it by finding the first { and using json.JSONDecoder().raw_decode(text[idx:]), which correctly
consumes just the object and ignores trailing garbage. Shape:
{
"newFiles": ["/local/path/IMG_0001.JPG"],
"duplicates": [{"id": "<asset-uuid>", "filepath": "/local/path/IMG_0002.JPG"}],
"newAssets": [{"id": "<asset-uuid>", "filepath": "/local/path/IMG_0001.JPG"}]
}
Both newAssets and duplicates give {id, filepath} — record both into a persistent manifest
(asset ID + filename + source identity, see below). Both cases legitimately "belong" to this
sync: a duplicate still means this card is a valid source for the album-membership that upload run
established.
The core safety issue: scope prune diffs by source, not by album
The tempting naive prune approach: list everything in the Immich album, list what's still on the currently-mounted card, delete anything in the album but not on the card. This is only safe if exactly one source (one card) has ever fed that album. The moment a second card contributes to the same album — a spare/replacement card, a different camera — mounting card #2 alone and running that diff makes every surviving photo from card #1 (sitting in a drawer, not mounted) look "not on the card" and flags the entire first card's kept photos for deletion. This is a real, silent data-loss risk if the diff's output is trusted without a full manual review of every filename.
The fix: maintain a manifest (volume_uuid, asset_id, filename, synced_at — TSV is fine) written by
the sync script on every run, and have the prune tool scope its diff to only the rows matching the
currently-mounted card's own Volume UUID. A second card's prune run then structurally cannot see,
and cannot touch, the first card's manifest rows — verified by directly calling the manifest-lookup
function with a fabricated UUID and confirming it returns zero rows, rather than trusting the logic
by inspection alone.
If a prune tool like this is being retrofitted onto assets that predate the manifest, backfill it:
compute (all current album assets) − (assets already confirmed absent from the card) = the set
that's demonstrably still present under a matching filename right now, and write those in as
manifest rows for the currently-mounted card's UUID before relying on the tool going forward.
Deleting: trash vs. permanent
DELETE /api/assets with body {"ids": [...], "force": false} → soft delete (moves to trash,
recoverable within Immich's retention window). force: true → permanent, immediate. Always use
force: false for anything automation-driven; a human can empty the trash themselves later if
they're sure. Requires the asset.delete permission on the API key (deliberately not included in
the baseline upload-only key — add it as a separate, explicit step only when building the prune
capability, and tell the user exactly what permission is being added and why).
Listing album contents needs the search endpoint, not the album endpoint
GET /api/albums/{id} does not return the member assets by default in current Immich versions
(no assets key in the response, and ?withoutAssets=false doesn't change that as of this
writing). To list an album's assets with filenames, use POST /api/search/metadata with
{"albumIds": ["<id>"], "size": 1000, "page": N} and follow assets.nextPage until it's null.
Testing without waiting on a real large upload
A multi-GB real card upload can take an hour+; don't block iteration on it. Validate the trigger
chain and script logic with a small synthetic disk image first (see above), and validate a real API
key's permissions with a tiny real (non-dry-run) upload of a throwaway generated image
(sips -s format jpeg <any .heic> --out test.jpg) into a clearly-named disposable test album —
delete it via the trash endpoint once confirmed. Watch for checksum collisions between multiple
test files generated the same way from the same source image — Immich dedups by content, so two
"different" test files with identical bytes will silently resolve to the same underlying asset,
which can leak a test asset into the wrong album as a side effect (harmless, but confusing until
traced back to the matching checksum).
Successor (2026-10-07): SD card → R2 directly, and the macOS privacy trap it hit
Immich was decommissioned; the camera backup now goes straight to R2 (mac-tools/sdcard-r2-sync/ in the homelab
planning repo: per-file single-part upload, R2 MD5 verified before the manifest row, no deletes, Keychain credentials).
A launchd job can't read a removable volume. A LaunchAgent running /bin/bash on StartOnMount can list
/Volumes, but find /Volumes/<card>/DCIM fails with Operation not permitted (Removable Volumes privacy). A
background process gets no "Allow?" prompt, so it is refused silently. Fix without granting Full Disk Access to bash:
wrap the script in a tiny app (osacompile -o "~/Applications/SD Card Backup.app" -e 'do shell script "…"', ad-hoc
codesign, LSUIElement), have the LaunchAgent open -g -j the app, and open it once interactively so macOS asks
the app for removable-volume access. Also: a run that examined zero files must never report success. The first
version said "0 backed up, 0 already safe. Safe to wipe" on a card it couldn't read.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |