Archivist¶
Archivist recursively extracts ZIP files, restores timestamps, and removes the metadata left in AppleDouble, Windows, and Synology formats. Explicit image workflows inventory pictures on disk and inside ZIPs, then move or copy approved selections into a flat destination.
Install with uv, preview your first folder, and safely apply the changes.
Learn how recursive extraction, existing folders, dry runs, and reports work.
Compare extraction and cleanup with picture inventory, move and copy in visual guides, with the options for each stage.
Review every command-line option and its matching environment variable.
Connect a local client for bounded picture inventory and transfer previews.
Run the distroless image as a non-root user with Docker or Compose.
Understand skipped archives, permissions, reports, and exit codes.
Set up a development environment, run tests, and understand the project.
What Archivist does¶
ZIPs found inside other ZIPs are processed in the same run, up to ten levels deep.
Remove AppleDouble, .DS_Store, Thumbs.db, desktop.ini, and @eaDir artifacts.
Every run is a preview until you explicitly pass --apply.
Free-space and expansion-ratio checks guard against oversized archives and ZIP bombs.
Use --send-to-bin to move removed items to the Recycle Bin or Trash.
See extracted, removed, overwritten, and skipped items in the console and log file.
Preview before anything changes¶
Run Archivist without --apply to inspect every planned extraction and cleanup. When the report
looks right, run the same command with --apply.
archivist --parent-folder "C:\photos"
archivist --parent-folder "C:\photos" --apply --send-to-bin
Product planning¶
The business requirements record the approved business scope, human approval, and measurement waiver. The image workflow specification records the implemented CLI workflow and settled policies; formal product/release sign-off and business measurements remain separate. The future capability specification preserves deferred generic file categories (including STL/3MF), mixed-ZIP policy options, and the independent conversational/AG-UI direction.