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.

🌐 Website

🪟 Also available for Windows: windows-cleaner-cli

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 only what you chose

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.

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.

# 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 • ⏎ submit

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

• Moving does not free disk space. The files still occupy the same volume. Space is only reclaimed by backup --clean, which deletes backups older than 7 days permanently.
• Docker and Homebrew cannot be backed up. Their cleanup is performed by the external tool (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

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:

1. Fork the repo
2. Create your branch: git checkout -b feat/my-feature
3. Make your changes and add tests
4. Run bun run lint && bun run test
5. Open a Pull Request

Looking for a place to start? Check issues labeled good first issue or help wanted.

• GitHub Discussions — questions, ideas, show & tell
• Issues — bug reports and feature requests

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