⚡ Quick Start

npx clean-my-mac-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 clean-my-mac-cli

🧹 Clean My Mac
──────────────────────────────────────────────────────

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)

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 clean-my-mac-cli — no complex flags | | 🎯 Interactive | Select exactly what you want to clean with checkboxes | | 🛡️ 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

🟢 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 clean-my-mac-cli

# Include risky categories
npx clean-my-mac-cli --risky

Uninstall Apps

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

npx clean-my-mac-cli uninstall

Maintenance Tasks

# Flush DNS cache (may require sudo)
npx clean-my-mac-cli maintenance --dns

# Free purgeable space
npx clean-my-mac-cli maintenance --purgeable

Other Commands

# List all available categories
npx clean-my-mac-cli categories

# Manage configuration
npx clean-my-mac-cli config --init
npx clean-my-mac-cli config --show

# Manage backups
npx clean-my-mac-cli backup --list
npx clean-my-mac-cli backup --clean

💻 Global Installation

If you use this tool frequently:

npm install -g clean-my-mac-cli
clean-my-mac-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

git clone https://github.com/guhcostan/clean-my-mac.git
cd clean-my-mac
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

📄 License

MIT License — see LICENSE for details.