Cleanser Documentation

A blazing-fast cross-platform CLI tool for clearing storage space, written in Rust.

loading...
Cleanser Crab

Installation

Choose your preferred installation method:

Homebrew (macOS)

brew tap phpfc/cleanser && brew install cleanser

Cargo

cargo install --git https://github.com/phpfc/cleanser.git

From Source

git clone https://github.com/phpfc/cleanser.git cd cleanser cargo build --release sudo cp target/release/cleanser /usr/local/bin/

Direct Download

Download pre-built binaries from the releases page.

Quick Start

Get up and running with Cleanser in seconds:

# Scan your system for cleanable files cleanser scan # Preview what would be deleted cleanser clean --dry-run # Clean safe items only cleanser clean --risk safe
Tip Always use --dry-run first to preview what will be deleted before running the actual clean command.

scan

Scan the filesystem for cleanable files and directories.

cleanser scan [OPTIONS] Primary

Analyzes your filesystem to find files that can be safely deleted, including caches, temporary files, build artifacts, and large files.

Option Description Default
-s, --speed <SPEED> Scan speed: quick, normal, or thorough normal
-p, --paths <PATHS> Specific paths to scan $HOME
--ignore <PATTERNS> Directories to exclude from scanning -
--min-size <MB> Minimum file size in MB for large file detection 100
--size-range <RANGE> Filter by size range (e.g., 100MB-500MB) -
--older-than <DURATION> Only files older than duration (e.g., 90d, 2w, 6m) -
--newer-than <DURATION> Only files newer than duration -
--max-depth <N> Maximum depth for directory traversal -
--find-duplicates Find duplicate files false
--interactive Launch interactive TUI browser false
--json Output results as JSON false
--no-cache Don't save scan results to cache false

Scan Speed Levels

Speed Description Depth
quick Fast scan for immediate results 3
normal Balanced scan 6
thorough Deep scan for comprehensive results unlimited

clean

Delete files based on risk level.

cleanser clean [OPTIONS] Destructive

Deletes files found by the scan command based on the specified risk level. Uses cached scan results by default.

Option Description Default
-r, --risk <LEVEL> Maximum risk level: safe, moderate, or risky safe
-y, --yes Skip confirmation prompts false
--dry-run Preview what would be deleted without deleting false
--force-scan Force a fresh scan instead of using cache false
--interactive Review and select files interactively false
Warning This command permanently deletes files. Always use --dry-run first to preview changes.

map

Manage the intelligent filesystem map for faster scans.

cleanser map <ACTION> Utility

Cleanser builds an intelligent map of your filesystem to enable faster repeated scans and better classification of directories.

Actions

Action Description
show View mapped directories and summary
stats Detailed breakdown by category and type
rebuild Force rebuild the filesystem map
verify Check if mapped paths still exist
suggest Suggest paths to add to whitelist

Rebuild Options

Option Description Default
--max-depth <N> Maximum depth for scanning 10
--min-confidence <F> Minimum confidence level (0.0-1.0) 0.6
Detective Crab

whitelist

Manage permanent exclusions from scanning and cleaning.

cleanser whitelist <ACTION> Config

Paths added to the whitelist will never be scanned or included in clean operations.

Action Description
add <PATH> Add a path to the whitelist
remove <PATH> Remove a path from the whitelist
list Show all whitelisted paths
# Protect an important directory cleanser whitelist add ~/important-project # View all protected paths cleanser whitelist list

cache

Manage scan result cache.

cleanser cache <ACTION> Utility

Cleanser caches scan results to speed up subsequent clean operations.

Action Description
show View cache information (age, items, size)
clear Clear the scan cache

Risk Levels

Cleanser categorizes files into three risk levels to help you make informed decisions about what to delete.

Level What's Included Recommendation
Safe System caches, browser caches, package manager caches (npm, pip, cargo), logs, __pycache__, temp files Delete without worry - these are regenerated automatically
Moderate node_modules, target/ (Rust), build/, dist/, .gradle, .next, .nuxt Great for developers - can be rebuilt with package managers
Risky Large files (> 100MB), duplicate files Review carefully before deleting
Smart Validation Build directories are validated against project files. For example, target/ is only flagged if Cargo.toml exists in the parent directory.
Safety Crab

Platform Support

Cleanser works on all major operating systems and automatically detects platform-specific cache locations.

Platform Cache Locations
🍎 macOS ~/Library/Caches, ~/.cache, ~/Library/Logs
🐧 Linux ~/.cache, XDG paths, /var/log
🪟 Windows %LOCALAPPDATA%, %TEMP%

Examples

Common usage patterns for Cleanser.

Basic Usage

# Quick scan of your home directory cleanser scan # Preview safe deletions cleanser clean --dry-run # Clean safe items with confirmation cleanser clean --risk safe

Developer Workflow

# Scan your projects directory cleanser scan --paths ~/Projects # Clean build artifacts (node_modules, target, etc.) cleanser clean --risk moderate # Protect important project from cleaning cleanser whitelist add ~/Projects/production-app

Finding Large Files

# Find files larger than 500MB cleanser scan --min-size 500 # Find files between 100MB and 1GB cleanser scan --size-range 100MB-1GB # Find old large files (not modified in 90 days) cleanser scan --min-size 100 --older-than 90d

Interactive Mode

# Browse and select files to delete with TUI cleanser scan --interactive # Interactively review files by risk level cleanser clean --risk moderate --interactive

Finding Duplicates

# Find duplicate files cleanser scan --find-duplicates # Output results as JSON for scripting cleanser scan --find-duplicates --json

Automation

# Clean safe items without prompts (for scripts/cron) cleanser clean --risk safe -y # Force fresh scan before cleaning cleanser clean --force-scan --risk safe -y
Permanent Deletion Cleanser permanently deletes files. They cannot be recovered from the trash. Always use --dry-run first and consider backing up important data.