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.

macOS Installation

When downloading Cleanser directly on macOS, you'll need to authorize the app since it's not signed with an Apple Developer certificate.

Installing the Desktop App (.dmg)

  1. Download the .dmg file for your Mac (Apple Silicon or Intel)
  2. Double-click the .dmg to open it
  3. Drag Cleanser to the Applications folder
  4. Try to open Cleanser - macOS will show a security warning
  5. Open System Settings → Privacy & Security
  6. Scroll down to find the message about Cleanser being blocked
  7. Click "Open Anyway"
  8. Confirm by clicking "Open" in the dialog
Why does this happen? macOS Gatekeeper blocks apps from unidentified developers. Since Cleanser is open-source and not signed with a paid Apple Developer certificate, you need to manually authorize it. This is a one-time process.

Installing the CLI (.tar.gz)

# Extract the archive tar -xzf cleanser-*.tar.gz # Move to a directory in your PATH sudo mv cleanser /usr/local/bin/ # Remove quarantine attribute (bypass Gatekeeper) sudo xattr -d com.apple.quarantine /usr/local/bin/cleanser
Alternative: Homebrew The easiest way to install on macOS is via Homebrew: brew tap phpfc/cleanser && brew install cleanser. This handles all the signing automatically.

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
--trash Move files to trash instead of permanent deletion false
--secure Securely overwrite files before deletion (DoD 5220.22-M) false
--secure-passes <N> Number of overwrite passes (1-35) 3

Deletion Methods

Method Description Speed
Standard Normal filesystem deletion (default) Fastest
Trash (--trash) Move to recoverable trash Fast
Secure (--secure) Overwrite with zeros, ones, then random data Slower
Warning Standard and secure deletion permanently remove files. Use --dry-run first to preview, or --trash for recoverable deletion.

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

trash

Manage the recoverable trash instead of permanently deleting files.

cleanser trash <ACTION> Recovery

Move files to a recoverable trash instead of permanently deleting them. Items in trash can be restored or permanently deleted later.

Action Description
list Show all items in trash with size and age
restore <ID> Restore an item to its original location
delete <ID> Permanently delete an item from trash
empty Permanently delete all items in trash
stats Show trash statistics and location

Options

Option Description
--to <PATH> Restore to a custom location instead of original
--secure Use secure deletion when emptying trash
-y, --yes Skip confirmation when emptying
--json Output as JSON
# Clean files to trash instead of permanent deletion cleanser clean --trash # View items in trash cleanser trash list # Restore a file (use ID from list) cleanser trash restore abc12345 # Empty trash to free space cleanser trash empty
Trash Location Trash is stored in ~/.cleanser/trash/. Use cleanser trash stats to see the exact location and total size.

schedule

Automate disk cleanup with scheduled jobs using your system's native scheduler.

cleanser schedule <ACTION> Automation

Create, manage, and run automated cleanup jobs. Uses platform-specific schedulers: launchd (macOS), systemd (Linux), or Task Scheduler (Windows).

Action Description
set <NAME> Create a new scheduled job
list Show all scheduled jobs
remove <NAME> Delete a scheduled job
enable <NAME> Enable a disabled job
disable <NAME> Temporarily disable a job
run <NAME> Run a job immediately
history Show job execution history

Schedule Frequencies

Format Description Example
daily Run once per day at midnight daily
daily@HH:MM Run daily at specific time daily@14:30
weekly Run once per week (Sunday) weekly
weekly@DAY Run weekly on specific day weekly@friday
monthly Run on the 1st of each month monthly
every Xh Run every X hours every 6h
cron Standard cron expression 0 3 * * 0

Job Options

Option Description Default
-f, --frequency Schedule frequency (required) -
-r, --risk Maximum risk level to clean safe
-p, --paths Specific paths to clean $HOME
--trash Move to trash instead of delete false
--secure Use secure deletion false
--notify Send notification on completion false
# Create a daily cleanup job cleanser schedule set daily-cleanup -f daily@03:00 # Weekly cleanup with moderate risk level cleanser schedule set weekly-deep -f weekly@sunday -r moderate # Cleanup every 6 hours, moving to trash cleanser schedule set frequent -f "every 6h" --trash # List all scheduled jobs cleanser schedule list # View execution history cleanser schedule history # Run a job manually cleanser schedule run daily-cleanup

Platform Integration

Platform Scheduler Config Location
🍎 macOS launchd ~/Library/LaunchAgents/
🐧 Linux systemd ~/.config/systemd/user/
🪟 Windows Task Scheduler System Task Scheduler
Best Practice Schedule cleanup jobs during off-hours (e.g., 3 AM) to avoid interfering with your work. Use the --trash flag initially to allow recovery if needed.

Desktop Application

Cleanser also comes as a desktop GUI application, built with Tauri and React. It provides a visual interface for disk cleanup with all the power of the CLI.

Features

Feature Description
Scan View Visual overview of cleanable files grouped by category with size breakdown
Risk Indicators Color-coded risk levels (green=safe, yellow=moderate, red=risky)
Map View Filesystem map statistics and management
Settings Configure scan parameters, language (EN/PT-BR), and theme
Whitelist Add/remove protected paths via native folder picker

GUI Installation

Download pre-built binaries or build from source.

Pre-built Binaries

Download the latest release for your platform from the Releases page:

Platform Formats
🍎 macOS .dmg, .app
🐧 Linux .deb, .AppImage
🪟 Windows .msi, .exe

Build from Source

Requires Rust 1.70+ and Node.js 18+.

# Clone the repository git clone https://github.com/phpfc/cleanser.git cd cleanser # Install frontend dependencies cd crates/cleanser-gui/ui npm install # Build the desktop app cd .. cargo tauri build

The built app will be in crates/cleanser-gui/target/release/bundle/.

Development Mode

Run the GUI with hot reload for development:

# Terminal 1: Start Vite dev server cd crates/cleanser-gui/ui npm run dev # Terminal 2: Start Tauri with hot reload cd crates/cleanser-gui cargo tauri dev

GUI Configuration

Configure scan settings and preferences in the Settings modal (gear icon in the header).

Scan Settings

Setting Description Default
Minimum file size Only detect large files above this threshold 100 MB
Find duplicates Enable duplicate file detection (slower scan) Off

Appearance

Setting Options
Language English, Português (BR)
Theme System, Light, Dark

Using the GUI

Scanning:

  1. Select scan speed: Quick (depth 3), Normal (depth 6), or Thorough (unlimited)
  2. Click Scan to start
  3. Review results grouped by category

Cleaning:

  1. Select items by clicking them or use category headers to select all in a category
  2. Review selected size at the bottom of the screen
  3. Click Clean Selected to delete

Managing Protected Paths:

  1. Open Settings (gear icon)
  2. Scroll to Protected Paths
  3. Click Add and select a folder using the native picker
  4. The folder and all its contents will be excluded from scans
Tip Use the Map tab to view filesystem statistics and rebuild the map if scans seem incomplete or slow.

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.