Skip to content
lvwxxPublic

About

Disk cleanup tool for macOS

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

Repository files navigation

clear

A disk cleanup CLI for macOS. The command is clr. By default it only scans and lists what it finds; nothing is deleted unless you pass --clean, and deleted items go to the Trash unless you pass --permanent.

Install

cargo install --path .

Usage

clr disk                          # Volume capacity, used, available (incl. purgeable) and usage %
clr cpu                           # Load average and the apps using the most CPU
clr cpu --clean                   # Pick apps to quit (sends SIGTERM for a normal shutdown)
clr junk                          # Caches, logs, Xcode, iOS backups, Trash, dev tool caches
clr junk --category dev,xcode     # Only some categories
clr large --min 1G --older 90d    # Files ≥ 1G not accessed in 90 days
clr large --dirs                  # Directories under HOME using the most space
clr projects --older 30d          # target, node_modules, .venv etc. in projects untouched for 30 days
clr dupes ~/Downloads             # Duplicate files (≥ 1M by default; skips node_modules and Go/Rust/npm caches)
clr uninstall                     # List all apps, sorted by size
clr uninstall --clean             # Pick apps to uninstall, then confirm the files to remove
clr uninstall "Cleaner One Pro"   # Uninstall by Finder name, file name or bundle ID, incl. helpers and crash reports

Global options:

Option Effect
--clean Pick items to delete after scanning (large starts with nothing checked; others start with everything checked)
--permanent Delete permanently instead of moving to the Trash
-y, --yes Skip the picker and delete everything found
--json JSON output; requires --yes when combined with --clean

Exit codes: 0 success, 1 some items failed to delete, 2 bad arguments or other errors.

Custom rules

Add rules in ~/.config/clear/rules.toml, or override a built-in rule by reusing its id (see src/rules.toml):

[[rule]]
id = "my-build"
category = "dev"
paths = ["~/workspace/*/target"]
desc = "Rust build output"

Safety

  • Protected paths are checked before deleting: system directories, HOME itself, and folders such as ~/Documents themselves are never removed. If a parent is a symlink, the real path is checked again.
  • Scans never follow symlinks or cross filesystems.
  • Moving to the Trash uses NSFileManager instead of Finder, so there are no password prompts. If NSFileManager refuses a file (it sometimes reports "no permission" for files you own and can write, e.g. recordings made by some apps), clr falls back to moving it straight into ~/.Trash; files moved this way have no "Put Back".
  • uninstall only matches leftovers by exact bundle ID, and refuses to uninstall an app that is running.
  • Paths that can't be read are skipped and reported at the end. For a complete scan, grant your terminal Full Disk Access in System Settings › Privacy & Security.

Recent changes

  • Trash fallback: files NSFileManager can't trash are moved into ~/.Trash directly instead of failing; name clashes get a .1, .2, … suffix.
  • disk and cpu commands: show volume usage, and list CPU-heavy apps with an option to quit them.
  • projects command: find and clean rebuildable build output (target, node_modules, .venv, …) in stale projects.
  • Uninstall improvements: list all apps, match by Finder display name, clean orphan leftovers by bundle ID, and explain container permission errors.
  • No password prompts when trashing duplicates.

Development

cargo test

Integration tests use CLR_HOME to point at a fake HOME and CLR_TRASH_DIR to redirect "move to Trash" into a temp directory.

About

Disk cleanup tool for macOS

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages