🧹 Mac Cleaner CLI

Free & Open Source Mac cleanup tool

Scan and remove junk files, caches, logs, and more — all from your terminal.

🪟 Also available for Windows: windows-cleaner-cli

---

⚡ Quick Start

``bash
npx mac-cleaner-cli
`

That's it! No installation needed. The CLI will:

1. 🔍 Scan your Mac for cleanable files
2. 📋 Show you what was found with sizes
3. ✅ Let you select exactly what to clean
4. 🗑️ Clean the selected items safely

🎬 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 flags |
| 🎯 Interactive | Select exactly what you want to clean with checkboxes |
| 📁 File Explorer | Drill down (→) into supported 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 |

🎯 What It Cleans

$3

| 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 |

$3

| 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 |

$3

| 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

$3

`bash


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 -f
`

$3

In interactive mode, you can drill into some categories and select specific folders/files to delete:

- Controls: ↑↓ navigate • ← back • → enter • space select • a all • i invert • ⏎ submit
- Supported categories include: User Cache Files (system-cache), Temporary Files (temp-files), System Log Files (system-logs), Development Cache (dev-cache), Browser Cache (browser-cache), Homebrew Cache (homebrew)

$3

Remove applications completely with all their preferences, caches, and support files:

`bash
npx mac-cleaner-cli uninstall
`

$3

`bash


Flush DNS cache (may require sudo)

npx mac-cleaner-cli maintenance --dns

Free purgeable space

npx mac-cleaner-cli maintenance --purgeable
`

$3

`bash


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 --clean
`

$3

`bash


Show help

npx mac-cleaner-cli -h # or --help

Show version

npx mac-cleaner-cli -V # or --version

Directory paths shown in absolute format

npx mac-cleaner-cli -A # or --absolute-paths
`

💻 Global Installation

If you use this tool frequently:

`bash
npm install -g mac-cleaner-cli
mac-cleaner-cli
`

🔒 Security

| | |
|---|---|
| ✅ Open Source | All code publicly available for audit |
| ✅ No Network | Operates 100% offline |
| ✅ 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

`bash
git clone https://github.com/guhcostan/mac-cleaner-cli.git
cd mac-cleaner-cli
npm install
npm run dev # Run in dev mode
npm test # Run tests
npm run lint # Run linter
npm run build # Build for production
`

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

💚 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.

---

⚠️ 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