Repo: dhcgn/immich-admin-cli

Problem

I self-host all my images in Immich — hundreds of thousands of photos and videos, a few TB. As a hobby photographer I needed an admin command line tool to handle bulk cases efficiently. Combined with AI agents like Hermes, I can work well with that large amount of images.

Tech Overview

Aspect	Choice
Stack	Go CLI (immich-admin)
API	Immich REST, ~23 endpoints via generated client
Safety	--dry-run preview, destructive step requires --yes, trash by default
Helpers	Optional cjxl / cjpegli, ImageMagick, ffmpeg for reencode/resize paths
Update	Self-update via gh-update

No warranty. Bulk delete/replace/re-encode can cause permanent data loss — keep a verified backup and test on non-critical data first.

Solution

Client workflows combine several API calls with local processing into one command:

immich-admin client-workflow replace-asset <ASSET_ID> <NEW_FILE>
immich-admin cw find-no-thumbhash --type IMAGE -q > corrupt-ids.txt
immich-admin cw repair-assets --mode all --check-all-assets --yes
immich-admin cw download-album --album-name "2025-07-04 Garten" --target-dir ./garten --size original --sync --yes

What this covers:

• replace-asset — upload, checksum-verify, copy metadata (albums, favorite, links, stack), trash original.
• find-no-thumbhash — read-only scan for corrupt/unprocessed assets.
• repair-assets — fix missing-JPEG-EOI and zero-count TIFF IFD defects, delete unrecoverable Google Takeout JSON sidecars (takeout-json mode only).
• tag-delete, add-users-to-album-with-pattern, fix-album-dates — regex bulk ops with preview.
• download-album — mirror one album locally with manifest-based --sync, optional resize/re-encode.

Outlook

Planned: reencode-jxl (lossless JPEG transcode via cjxl) and reencode-jpegli on top of the same replace flow. See the repo README for the full flag reference and API coverage table.