Getting Started

Requirements

  • Python 3.10 or later

  • uv, which provides uvx

  • Windows 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

  1. Open a terminal and choose a folder whose contents you can inspect.

  2. 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.

  1. Review the report. Confirm the listed archives, cleanup targets, and skipped items.

  2. Apply the changes. Add --send-to-bin if 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