mac-cleaner-cli
⚡ Quick Start
npx mac-cleaner-cli
That's it. No installation needed. The CLI will:
- 🔍 Scan your Mac for cleanable files
- 📋 Show you what was found with sizes
- ✅ Let you select exactly what to clean
- 🗑️ Clean only what you chose
🖥️ Desktop App (menu bar) — new
Prefer not to open a terminal? Mac Cleaner is a menu bar app built on the same scanners as the CLI.
- 🧹 Cleans automatically every day at the time you pick (temp files, browser cache, logs — you choose). If your Mac was asleep, it catches up when it wakes.
- ⚡ Clean Now from the menu bar whenever you want
- 🔥 Deep Clean (hard delete) — scan many more places, review the biggest items per category and permanently delete only what you tick, after a confirmation
- 📊 History of every run with the space freed per category, plus a notification after each automatic clean
- 🛡️ Risky categories are never cleaned unattended, and recently used temp files are left alone
Install or update it with one command:
npx mac-cleaner-cli app install
# or, without Node.js:
curl -fsSL https://guhcostan.github.io/mac-cleaner-cli/install.sh | bash
Both pick the build for your Mac (Apple Silicon or Intel), download the latest release, verify its SHA-256 checksum and install it into /Applications. Then give it Full Disk Access (System Settings → Privacy & Security) so it can see every cache.
The .dmg files are also on Releases, but the app isn't signed with an Apple Developer ID yet, so a .dmg downloaded with a browser shows a Gatekeeper warning first (why, and how to open it). See desktop/ for details and how to build it yourself.
🎬 The CLI In Action
✨ Features
| Feature | Description |
|---|
| 🚀 One Command | Just run npx mac-cleaner-cli — no complex setup |
| 🎯 Interactive | Select exactly what you want to clean with checkboxes |
| 📁 File Explorer | Drill down (→) into categories to select specific folders/files |
| 🛡️ Safe by Default | Risky items hidden unless you use --risky |
| 👀 Dry Run | Preview exactly what would be deleted with --dry-run |
| ♻️ Optional Backups | Move items to a backup folder instead of deleting, restore later |
| 🤖 Scriptable | scan --json and clean --categories … --yes for cron and CI |
| 🖥️ Menu Bar App | Daily automatic cleaning, Deep Clean and history — npx mac-cleaner-cli app install |
| 🔍 Smart Scanning | Finds caches, logs, dev files, browser data, and more |
| 📱 App Uninstaller | Remove apps completely with all associated files |
| 🔧 Maintenance | Flush DNS cache, free purgeable space |
| 🔒 Privacy First | 100% offline — no data ever leaves your machine |
| 📦 Minimal Dependencies | Only 5 runtime deps, all from trusted maintainers |
💰 vs. Paid Alternatives
| Mac Cleaner CLI | CleanMyMac X | DaisyDisk |
|---|
| Price | Free | $39.95/year | $9.99 one-time |
| Open Source | ✅ | ❌ | ❌ |
| Telemetry / Analytics | ❌ None | ⚠️ Yes | ⚠️ Yes |
| Works via terminal | ✅ | ❌ | ❌ |
| Menu bar app | ✅ | ✅ | ❌ |
| Automatic daily cleaning | ✅ | ✅ | ❌ |
| CI/CD friendly | ✅ | ❌ | ❌ |
| Customizable | ✅ Fork it | ❌ | ❌ |
| App Uninstaller | ✅ | ✅ | ❌ |
| File-level selection | ✅ | ✅ | ✅ |
🎯 What It Cleans
🟢 Safe (always safe to delete)
| Category | What it cleans |
|---|
trash | Files in the Trash bin |
temp-files | Temporary files in /tmp and /var/folders |
browser-cache | Chrome, Safari, Firefox, Arc cache |
🟡 Moderate (generally safe)
| Category | What it cleans |
|---|
system-cache | Application caches in ~/Library/Caches |
system-logs | System and application logs |
dev-cache | npm, yarn, pip, Xcode DerivedData, CocoaPods |
node-modules | Stale dependencies beside package.json (moderate) |
rust-artifacts | target beside Cargo.toml (moderate) |
node-build-artifacts | Node build output beside package.json (risky) |
go-artifacts | Ignored bin/dist beside go.mod (risky, explicit opt-in) |
homebrew | Homebrew download cache and old formula versions (brew cleanup --prune=all) |
docker | Unused images, stopped containers, build cache — only the types you select |
docker and homebrew are not "safe": their cleanup is performed by the
external tool, and it removes more than downloaded files. Docker removes images
that aren't used by a running container (they must be pulled or rebuilt
again), and Homebrew removes old formula versions. Docker volumes are never
touched — that's your data, not cache.
🔴 Risky (use --risky flag)
| Category | What it cleans |
|---|
downloads | Downloads older than 30 days |
ios-backups | iPhone and iPad backup files |
mail-attachments | Downloaded email attachments |
duplicates | Duplicate files (keeps newest) |
large-files | Files larger than 500MB |
language-files | Unused language localizations — breaks the app's code signature |
git-worktrees | Stale or orphaned git worktrees (agents, feature checkouts) |
📖 Usage
Basic Usage
# Interactive mode — scan, select, and clean
npx mac-cleaner-cli
# Include risky categories
npx mac-cleaner-cli --risky
# Preview what would be deleted, without deleting anything
npx mac-cleaner-cli --dry-run
# Enable file picker for all categories
npx mac-cleaner-cli --risky -f
Folder-Level Selection (Interactive)
In interactive mode, press → on supported categories to drill into specific folders/files:
↑↓ navigate • ← back • → enter • space select • a all • i invert • ⏎ submit
This is the beginning of the README. Read the rest at the original. Read the full README ↗
