putzen-cli 3.3.0

helps keeping your disk clean of build and dependency artifacts safely
Documentation

License: GPL v3 crates.io dependency status Build Status

"putzen" is German and means cleaning. It helps keeping your disk clean of build and dependency artifacts safely.

demo

New: putzen caches

Interactive TUI for cleaning user-level tool caches (~/.cargo, ~/.npm, ~/.cache/huggingface, …). Browse, mark, drill in, delete — in one screen.

caches demo

Higher-quality MP4

About

In short, putzen solves the problem of cleaning up build or dependency artifacts. It does so by a simple "File" -> "Folder" rule. If the "File" and "Folder" is present, it cleans "Folder"

It also does all this fast, means in parallel (if the filesystem supports it).

Supported Artifacts

putzen supports cleaning artifacts for:

type file that is checked folder that is cleaned
rust Cargo.toml target
javascript package.json node_modules
CMake CMakeLists.txt build

furthermore, it does also support:

  • It can do run a dry-run (-d)
  • Interactive asking for deletion
  • Sums up the space that will be freed

Quick Start

Install

On Linux as snap

Get it from the Snap Store

TL;DR:

sudo snap install putzen

With cargo

To install the putzen, you just need to run

cargo install putzen-cli

Note the binary is called putzen (without -cli)

to verify if the installation was successful, you can run which putzen that should output similar to

$HOME/.cargo/bin/putzen

Usage

$ putzen --help

Usage: putzen [-v] [--scores] [-d] [-y] [-L] [-a] [--no-hidden] [--hidden <hidden...>] [--] [<folder>]

help keeping your disk clean of build and dependency artifacts

Positional Arguments:
  folder            path where to start with disk clean up.

Options:
  -v, --version     show the version number
  --scores          show the stored highscore board and exit
  -d, --dry-run     dry-run will never delete anything, good for simulations
  -y, --yes-to-all  switch to say yes to all questions
  -L, --follow      follow symbolic links
  -a, --dive-into-hidden-folders
                    include every hidden directory (== --hidden '*')
  --no-hidden       skip every hidden directory (overrides the default
                    `.worktrees`)
  --hidden          glob of hidden directories to descend into (repeatable).
                    Match is against the full basename including the leading
                    dot, e.g. `.worktrees`, `.{worktrees,jj}`, `.work*`.
                    Default: `.worktrees`.
  --help, help      display usage information

For the interactive cache-cleaning TUI, run putzen caches:

$ putzen caches --help

Usage: putzen caches [--root <root...>] [--floor <floor>] [--dry-run] [-y]

interactive cleanup of user-level cache directories

Options:
  --root            scan root (repeatable). When given, REPLACES the built-in
                    defaults.
  --floor           caches whose newest file is younger than this are flagged
                    ACTIVE
  --dry-run         dry run: never delete, just show what would happen
  -y, --yes         skip the deletion confirmation modal
  --help, help      display usage information

Hidden directories

putzen skips hidden directories by default, except for .worktrees — projects that colocate git worktrees inside the repo get cleaned in one run.

  • --hidden <GLOB> — pick which hidden dirs to descend into (repeatable). Default: .worktrees. Glob is matched against the full basename including the leading dot, so write .worktrees, .{worktrees,jj}, .work*.
  • --no-hidden — skip all hidden directories (pre-3.x behavior).
  • -a / --dive-into-hidden-folders — descend into every hidden directory (equivalent to --hidden '*').

These three are mutually exclusive.

Highscores

Every putzen run earns you a little reward. The biggest single cleanup and the biggest total run ever measured are kept as a tiny gold/silver/bronze podium. Keep running it on your machine and watch your records stack up over time — show the board any time with --scores:

❯ putzen --scores

   ──── ★ SINGLE CLEANUP ★ ────
     🥇 Gold
         40.1GiB · 2026-03-14
   ────────────────────────────
     🥈 Silver
         37.9GiB · 2026-03-10
   ────────────────────────────
     🥉 Bronze
          6.5GiB · 2026-03-14
   ────────────────────────────

   ──── ★    TOTAL RUN   ★ ────
     🥇 Gold
         60.3GiB · 2026-03-14
   ────────────────────────────
     🥈 Silver
         44.6GiB · 2026-03-10
   ────────────────────────────
     🥉 Bronze
         19.6GiB · 2026-04-03
   ────────────────────────────

Caches

putzen caches scans known tool-cache locations under $HOME (cargo, npm, pnpm, yarn, bun, uv, pip, huggingface, gradle, ivy, …) and presents them as a ranked list. You browse with arrow keys, drill into a cache to see its children, mark anything to delete with Space, and confirm with d + y.

Pass --root <dir> to scan a tree of your choosing instead of the built-in defaults.

The score

Each cache gets a single number that ranks "how much disk this is wasting right now":

score = size_MiB × age_days
  • size_MiB — total size of the cache directory.
  • age_days — days since its newest file was last touched.

The intuition: a 5 GiB cache you used yesterday is probably still useful; a 200 MiB cache untouched for a year is dead weight, and the score keeps it visible. The right-pane heatmap bar is score / max_score — the heaviest cache in your visible set is full-red, everything else scales down through orange to green.

Score is the default sort order. Press s to cycle through score → size → age when you want to rank by a single dimension instead.

The --floor <duration> flag (e.g. --floor 14d) marks caches younger than that threshold as ACTIVE — marking them for deletion needs an extra confirmation modal so a fresh cache you're still using doesn't disappear by accident. Default floor: 7 days.

Alternative Projects

License