gem-hunter
Language: TypeScript
Free macOS CLI to clean disk space — caches, logs, Homebrew, Xcode. Open-source alternative to CleanMyMac
Free up disk space on macOS with a single command. Removes caches, logs, Homebrew leftovers, Xcode DerivedData, and junk files — all from your terminal.
No subscription. No telemetry. No bloatware.
🪟 Also available for Windows: windows-cleaner-cli
npx mac-cleaner-cli
That's it. No installation needed. The CLI will:
Prefer not to open a terminal? Mac Cleaner is a menu bar app built on the same scanners as the CLI.
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.
| 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 |
| 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 | ✅ | ✅ | ✅ |
| 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 |
| 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 |
Orphaned node_modules in old projects |
homebrew |
Homebrew download cache and old formula versions (brew cleanup --prune=all) |
docker |
Unused images, stopped containers, build cache — only the types you select |
dockerandhomebreware 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.
| 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) |
# 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
In interactive mode, press → on supported categories to drill into specific folders/files:
↑↓ navigate • ← back • → enter • space select • a all • i invert • ⏎ submitSupported categories: User Cache Files, Temporary Files, System Log Files, Development Cache, Browser Cache, Homebrew Cache.
# Scan only — see what can be cleaned without deleting anything npx mac-cleaner-cli scan # Machine-readable output for scripts and integrations npx mac-cleaner-cli scan --json npx mac-cleaner-cli scan --json --verbose # include item paths # Clean specific categories without prompts (great for cron/CI) npx mac-cleaner-cli clean --categories trash,browser-cache,homebrew --yes # Preview first npx mac-cleaner-cli clean --categories dev-cache --dry-run # Clean everything that is safe, no selection UI npx mac-cleaner-cli clean --all --yes
Risky categories (downloads, iOS backups, etc) are always skipped unless you pass --unsafe.
Remove applications completely with all their preferences, caches, and support files:
npx mac-cleaner-cli uninstall
# Flush DNS cache (may require sudo) npx mac-cleaner-cli maintenance --dns # Free purgeable space npx mac-cleaner-cli maintenance --purgeable # Delete Time Machine local snapshots (requires sudo, asks for confirmation) sudo npx mac-cleaner-cli maintenance --timemachine # Preview it first, or skip the prompt npx mac-cleaner-cli maintenance --timemachine --dry-run sudo npx mac-cleaner-cli maintenance --timemachine --yes
Local snapshots are taken automatically by Time Machine and can grow to hundreds of gigabytes. Deleting them is irreversible — they are your only local rollback point while the backup disk is disconnected — but macOS recreates them as needed once it is reconnected.
# List all available categories npx mac-cleaner-cli categories # Manage configuration npx mac-cleaner-cli config --init npx mac-cleaner-cli config --show # Manage backups npx mac-cleaner-cli backup --list npx mac-cleaner-cli backup --restore <dir> npx mac-cleaner-cli backup --clean # Install or update the menu bar app (--no-open, --dir <folder>) npx mac-cleaner-cli app install
By default, cleaning is permanent: files are removed with rm -rf and do
not go to the Trash.
You can opt into backups by setting backupEnabled in ~/.maccleanerrc:
{ "backupEnabled": true }With backups on, selected items are moved to ~/.mac-cleaner-cli/backup/<timestamp>/
instead of being deleted, and can be brought back with backup --restore.
Two honest caveats:
backup --clean, which deletes backups older than
7 days permanently.docker system prune, brew cleanup), so there is no file for
us to move. The CLI warns you before proceeding when these are selected.If a backup fails, the item is not deleted — it stays where it is and the failure is reported.
-V, --version Show version number -h, --help Show help -r, --risky Include risky categories -d, --dry-run Show what would be deleted, delete nothing -f, --file-picker Force file picker for ALL categories -A, --absolute-paths Show absolute paths --no-progress Disable progress bars
Scans tolerate unreadable paths (missing Full Disk Access, permission errors), so a
category can come back empty without an obvious reason. Set MAC_CLEANER_DEBUG=1 to
print every skipped path and the underlying error:
MAC_CLEANER_DEBUG=1 npx mac-cleaner-cli scan
Exit codes: 0 on success, 1 when a category could not be scanned or an item could
not be deleted. scan --json also reports failures in an errors array.
If you use this tool frequently:
npm install -g mac-cleaner-cli mac-cleaner-cli
| ✅ Open Source | All code publicly available for audit |
| ✅ No Network | Operates 100% offline (only app install talks to GitHub, to download the app) |
| ✅ No Root Required | All operations run as current user |
| ✅ Minimal Deps | Only 5 runtime dependencies |
| ✅ CI/CD | Every release tested with TypeScript, ESLint, and automated tests |
| ✅ Socket.dev | Dependencies monitored for supply chain attacks |
Found a vulnerability? Report it via GitHub Security Advisories.
git clone https://github.com/guhcostan/mac-cleaner-cli.git cd mac-cleaner-cli bun install bun run dev # Run in dev mode bun run test # Run tests bun run lint # Run linter bun run build # Build for production
Desktop app (Electron, lives in desktop/):
cd desktop bun install bun run start # Build and launch the menu bar app bun run test # Run desktop tests bun run dist # Package .dmg/.zip into desktop/release (macOS only) bun run screenshots # Regenerate the README screenshots with sample data (needs Playwright)
Contributions are very welcome! Whether it's a new scanner, a bug fix, or a documentation improvement — we'd love your help.
Read the full guide: CONTRIBUTING.md
Quick steps:
git checkout -b feat/my-featurebun run lint && bun run testLooking for a place to start? Check issues labeled good first issue or help wanted.
If this tool saved you disk space, a star goes a long way! It helps more Mac users discover this free alternative to paid cleaners.
If this tool saved you time or disk space, consider supporting the project!
Your support helps maintain and improve this tool. Thank you! 🙏
MIT License — see LICENSE for details.
⚠️ Disclaimer
This tool deletes files from your system. While we've implemented safety measures, always ensure you have backups of important data.
Made with ❤️ for Mac users everywhere