alibosworth/mac-cleaner-cli
macOS CLI to free disk space — clears caches, logs, Homebrew and Xcode junk
mac-cleaner-cli
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
⚡ Quick Start
npx mac-cleaner-cliThat'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
🎬 See It In Action
$ npx mac-cleaner-cli
🧹 Mac Cleaner CLI
──────────────────────────────────────────────────────
Scanning your Mac for cleanable files...
Found 44.8 GB that can be cleaned:
? Select categories to clean (space to toggle, enter to confirm):
❯ ◯ ● Trash 2.1 GB (45 items)
◯ ● Browser Cache 1.5 GB (3 items)
◯ ● Temporary Files 549.2 MB (622 items)
◯ ● User Cache Files 15.5 GB (118 items)
◯ ● Development Cache 21.9 GB (14 items)
↑↓ navigate • ← back • → enter • space select • a all • i invert • ⏎ submit
# Press → on a supported category to browse and select specific folders/files
? Browsing: Root Scan Results
❯ ◯ 📂 com.apple.Safari 1.2 GB
◯ 📂 com.google.Chrome 2.3 GB
◯ 📂 com.spotify.client 824.1 MB
↑↓ navigate • ← back • → enter • space select • a all • i invert • ⏎ submit
Summary:
Items to delete: 802
Space to free: 41.5 GB
? Proceed with cleaning? (Y/n)
✓ Cleaning Complete!
──────────────────────────────────────────────────────
Trash ✓ 2.1 GB freed
Browser Cache ✓ 1.5 GB freed
Temporary Files ✓ 549.2 MB freed
User Cache Files ✓ 15.5 GB freed
Development Cache ✓ 21.9 GB freed
──────────────────────────────────────────────────────
🎉 Freed 41.5 GB of disk space!
Cleaned 802 items
✨ 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 |
| 🔍 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 | ||
| Works via terminal | ✅ | ❌ | ❌ |
| 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 |
homebrew |
Homebrew download cache |
docker |
Unused Docker images, containers, volumes |
🟡 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 |
Orphaned node_modules in old projects |
🔴 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 |
📖 Usage
Basic Usage
# Interactive mode — scan, select, and clean
npx mac-cleaner-cli
# Include risky categories
npx mac-cleaner-cli --risky
# Enable file picker for all categories
npx mac-cleaner-cli --risky -fFolder-Level Selection (Interactive)
In interactive mode, press → on supported categories to drill into specific folders/files:
↑↓navigate •←back •→enter •spaceselect •aall •iinvert •⏎submit
Supported categories: User Cache Files, Temporary Files, System Log Files, Development Cache, Browser Cache, Homebrew Cache.
Uninstall Apps
Remove applications completely with all their preferences, caches, and support files:
npx mac-cleaner-cli uninstallMaintenance Tasks
# Flush DNS cache (may require sudo)
npx mac-cleaner-cli maintenance --dns
# Free purgeable space
npx mac-cleaner-cli maintenance --purgeableOther Commands
# 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 --cleanFlags
-V, --version Show version number
-h, --help Show help
-r, --risky Include risky categories
-f, --file-picker Force file picker for ALL categories
-A, --absolute-paths Show absolute paths
--no-progress Disable progress bars💻 Global Installation
If you use this tool frequently:
npm install -g mac-cleaner-cli
mac-cleaner-cli🔒 Security
| ✅ Open Source | All code publicly available for audit |
| ✅ No Network | Operates 100% offline |
| ✅ 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.
🛠️ Development
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🤝 Contributing
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:
- Fork the repo
- Create your branch:
git checkout -b feat/my-feature - Make your changes and add tests
- Run
bun run lint && bun run test - Open a Pull Request
Looking for a place to start? Check issues labeled good first issue or help wanted.
💬 Community
- GitHub Discussions — questions, ideas, show & tell
- Issues — bug reports and feature requests
⭐ Star History
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.
💚 Support
If this tool saved you time or disk space, consider supporting the project!
Your support helps maintain and improve this tool. Thank you! 🙏
📄 License
MIT License — see LICENSE for details.
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