README.md

duster

Disk cleanup CLI for developers. Finds and removes build artifacts, caches, and other space hogs.

Install

curl -fsSL https://github.com/raw/ericzakariasson/duster/main/install.sh | sh

Other install methods

With Cargo:

cargo install --git https://github.com/ericzakariasson/duster

Manual download:

• macOS Apple Silicon
• macOS Intel
• Linux x86_64

Commands

duster scan              # Find cleanable files (dry-run)
duster clean             # Select categories, then delete (with confirmation)
duster clean -y          # Delete without confirmation
duster analyze           # Detailed breakdown by category
duster space             # Total / free disk space (default: home fs)
duster space --path /tmp # For a specific path's filesystem
duster space --json      # Machine-readable output
duster tui               # Interactive TUI to visualize cleanable disk usage
duster config            # Show current settings

Categories

--cache       # App/system caches (~/.cache, ~/Library/Caches)
--trash       # Trash bin
--temp        # Temp files older than 1 day
--downloads   # Old files in ~/Downloads
--build       # Build artifacts from inactive projects (node_modules, target/, etc.)
--large       # Files over 100MB
--duplicates  # Duplicate files (by hash)
--old         # Files not accessed in 30+ days
--all, -a     # All categories (default if none specified)

Options

--min-age <DAYS>      # Age threshold for old files (default: 30)
--min-size <SIZE>     # Size threshold for large files (default: 100MB)
--project-age <DAYS>  # Projects inactive for this long are cleanable (default: 14)
--path <PATH>         # Scan path (default: home directory)
--exclude <PATTERN>   # Exclude matching paths (repeatable)
--json                # Output as JSON

Examples

# Quick cache cleanup
duster clean --cache --trash -y

# Find build artifacts from old projects
duster scan --build --project-age 30

# Large files over 500MB
duster scan --large --min-size 500MB

# Everything as JSON
duster scan --json

TUI Mode

Run duster tui for an interactive terminal visualization of cleanable disk space by category. Use up/down (or j/k) to move between categories and q to exit.

Config File

Optional: ~/.config/duster/config.toml

min_age_days = 30
min_large_size_mb = 100
project_recent_days = 14
download_age_days = 30
excluded_paths = ["important-project/node_modules"]
custom_paths = [
  { path = "~/Library/Application Support/Cursor Nightly", category = "cache", description = "Cursor Nightly app data" },
  { path = "~/Library/Caches/co.anysphere.cursor.nightly", category = "cache", description = "Cursor Nightly cache" },
  { path = "~/Library/Caches/co.anysphere.cursor.nightly.ShipIt", category = "cache", description = "Cursor Nightly updater cache" },
  { path = "~/dev/everysphere/anyrun/target", category = "build", description = "Anyrun build artifacts" }
]

Custom Clean Paths

Use custom_paths to include specific directories or files that duster doesn't discover automatically. Each entry supports:

• path: Absolute or ~/-relative path.
• category: One of cache, build, trash, temp, downloads, large, duplicates, old.
• description: Optional text shown in reports.
• min_size_mb: Optional size threshold (defaults to 1MB).

How Build Detection Works

Build artifacts (node_modules, target/, .gradle, etc.) are only flagged if the parent project hasn't been modified within --project-age days. This protects active projects.