Getting Started¶
Requirements¶
Python 3.10 or later
uv, which provides
uvxWindows or Linux
Send2Trash is the only base CLI runtime dependency. It is installed automatically
and powers the optional Recycle Bin and Trash behavior. The separate
read-only MCP adapter uses an optional [mcp] extra; it is not needed
for any CLI command below. MCP public launches require a reviewed immutable
commit containing the server, not the unpinned CLI examples on this page.
Run without installing¶
Open a terminal and choose a folder whose contents you can inspect.
Preview the work. This command downloads Archivist and performs a dry run:
uvx --from git+https://github.com/CoffeesoftDotDev/archivist archivist --parent-folder "C:\photos"
Important
Nothing is extracted or deleted without --apply. The preview still opens archives read-only and
performs free-space and ZIP-bomb checks.
Review the report. Confirm the listed archives, cleanup targets, and skipped items.
Apply the changes. Add
--send-to-binif removed items should go to the Recycle Bin or Trash:uvx --from git+https://github.com/CoffeesoftDotDev/archivist archivist --parent-folder "C:\photos" --apply --send-to-bin
Install the command¶
Install Archivist as a uv tool when you want a permanent command:
uv tool install git+https://github.com/CoffeesoftDotDev/archivist
archivist --parent-folder "C:\photos"
Both uvx and uv tool install accept a local clone path in place of the Git URL.
Choose the folder interactively¶
Leave out --parent-folder to select the folder through a terminal prompt. Non-interactive
environments, including Docker, require the folder to be configured.
Next steps¶
Choose a workflow with visual guides to extraction, cleanup, picture inventory, move and copy
Read Usage to understand extraction, existing folders, and reports
Review Configuration for every option and environment variable