mac-cleaner-cli

Free macOS CLI to clean disk space — caches, logs, Homebrew, Xcode. Open-source alternative to CleanMyMac

Automatically checked · GitHub checked 2026-11-17

mac-cleaner-cli

Overview

mac-cleaner-cli

mac-cleaner-cli — free macOS disk space cleaner CLI tool

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

npm version npm downloads CI License: MIT

Node.js Version Platform: macOS TypeScript Socket Badge

GitHub Stars GitHub Forks

Support on Ko-fi

🪟 Also available for Windows: windows-cleaner-cli


⚡ Quick Start

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

🖥️ Desktop App (menu bar) — new

Prefer not to open a terminal? Mac Cleaner is a menu bar app built on the same scanners as the CLI.

Mac Cleaner menu bar app: space freed, disk usage, last run and next automatic clean

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

Deep Clean asking to confirm a hard delete, the History of runs, and the Settings with the daily schedule

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.

🎬 The CLI In Action

mac-cleaner-cli demo

✨ Features

FeatureDescription
🚀 One CommandJust run npx mac-cleaner-cli — no complex setup
🎯 InteractiveSelect exactly what you want to clean with checkboxes
📁 File ExplorerDrill down (→) into categories to select specific folders/files
🛡️ Safe by DefaultRisky items hidden unless you use --risky
👀 Dry RunPreview exactly what would be deleted with --dry-run
♻️ Optional BackupsMove items to a backup folder instead of deleting, restore later
🤖 Scriptablescan --json and clean --categories … --yes for cron and CI
🖥️ Menu Bar AppDaily automatic cleaning, Deep Clean and history — npx mac-cleaner-cli app install
🔍 Smart ScanningFinds caches, logs, dev files, browser data, and more
📱 App UninstallerRemove apps completely with all associated files
🔧 MaintenanceFlush DNS cache, free purgeable space
🔒 Privacy First100% offline — no data ever leaves your machine
📦 Minimal DependenciesOnly 5 runtime deps, all from trusted maintainers

💰 vs. Paid Alternatives

Mac Cleaner CLICleanMyMac XDaisyDisk
PriceFree$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✅✅✅

🎯 What It Cleans

🟢 Safe (always safe to delete)

CategoryWhat it cleans
trashFiles in the Trash bin
temp-filesTemporary files in /tmp and /var/folders
browser-cacheChrome, Safari, Firefox, Arc cache

🟡 Moderate (generally safe)

CategoryWhat it cleans
system-cacheApplication caches in ~/Library/Caches
system-logsSystem and application logs
dev-cachenpm, yarn, pip, Xcode DerivedData, CocoaPods
node-modulesStale dependencies beside package.json (moderate)
rust-artifactstarget beside Cargo.toml (moderate)
node-build-artifactsNode build output beside package.json (risky)
go-artifactsIgnored bin/dist beside go.mod (risky, explicit opt-in)
homebrewHomebrew download cache and old formula versions (brew cleanup --prune=all)
dockerUnused images, stopped containers, build cache — only the types you select

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.

🔴 Risky (use --risky flag)

CategoryWhat it cleans
downloadsDownloads older than 30 days
ios-backupsiPhone and iPad backup files
mail-attachmentsDownloaded email attachments
duplicatesDuplicate files (keeps newest)
large-filesFiles larger than 500MB
language-filesUnused language localizations — breaks the app's code signature
git-worktreesStale or orphaned git worktrees (agents, feature checkouts)

📖 Usage

Basic Usage

# 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

Folder-Level Selection (Interactive)

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.

Scripting & Automation (non-interactive)

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

Repository artifacts

# Scan only a workspace; repeat --root for additional workspaces.
npx mac-cleaner-cli scan --category rust-artifacts --root ~/dev --json --verbose

# Simulate validated Node build cleanup as one JSON document.
npx mac-cleaner-cli clean --categories node-build-artifacts --unsafe --root ~/dev --dry-run --json

# Go requires explicit inclusion or an explicit Go category, plus risky enablement.
npx mac-cleaner-cli clean --categories go-artifacts --unsafe --root ~/dev --dry-run --json

# Live review: selections start empty. A separate confirmation precedes cleanup.
npx mac-cleaner-cli --live --root ~/dev
npx mac-cleaner-cli scan --live --root ~/dev

All repository rules require a readable, regular, non-symlink marker in the immediate parent. Node build names are .next, .turbo, .parcel-cache, coverage, dist, build, out, and .cache. Generic Node names (coverage, dist, build, out, .cache) and Go bin/dist additionally require a positive Git ignore match. They are omitted in non-Git projects. A marker or ignore match does not prove that every untracked file is disposable.

Git's current index and HEAD both protect tracked content, including staged additions/removals, conflicts, symlinks and submodules. Nested .git files/directories also protect candidate ancestors. Git failures, unreadable contents and incomplete inspection prevent eligibility. Candidate symlinks and traversal through symlinks below canonical roots are rejected. Node wins a Node/Go dist collision when both categories are requested; a Go-only request assigns it to Go.

Default roots are ~/Projects, ~/Developer, ~/Code, ~/dev, ~/workspace, and ~/repos. extraPaths.projects adds roots for all repository categories; legacy extraPaths.nodeModules adds roots only for node-modules. A nonempty repeatable --root list replaces these roots for that command, without changing other scanners. Roots are canonicalized and restricted to directories below HOME, /Users, or /Volumes; broad HOME/system roots are rejected. Empty extra-path arrays add nothing.

Add these settings to the existing ~/.maccleanerrc (or ~/.config/mac-cleaner-cli/config.json):

{
  "extraPaths": { "projects": ["~/work"], "nodeModules": [] },
  "excludePaths": ["**/keep.txt", "docs/build"],
  "includeEcosystems": [],
  "nodeModulesDaysOld": 30,
  "projectScanMaxDepth": 4,
  "parallelScans": true,
  "concurrency": 4
}

--exclude <pattern> repeats and adds to configured keep paths. A basename matches any component; slash-containing patterns match root-relative prefixes on component boundaries. * and ? match within a component, and ** as a whole component matches zero or more components. Absolute paths, traversal, empty patterns, negation, braces and brackets are invalid. Any excluded descendant protects its entire artifact directory, including across overlapping roots. Malformed repository policy fails closed.

Node dependencies must be at least nodeModulesDaysOld days old (integer 0–365, default 30), using the newer of the project-directory mtime and every candidate entry's newest mtime, including directories and links. projectScanMaxDepth is 0–16 (default 4): children of parents at depth 0 through 4 are inspected. Artifact contents are fully inspected regardless of this discovery cap. Known hidden worktree containers are traversed; dependency contents and Git metadata are pruned during discovery.

Node and Rust are enabled by default. --include go, config includeEcosystems: ["go"], or explicitly selecting go-artifacts opts into Go; --all, --unsafe, and --risky alone do not. defaultCategories narrows default category selection; excludeCategories always wins. Risky Node/Go categories start with no preselected files in interactive review. Scripted selection requires the existing explicit risky flag.

Selected repository items are revalidated against their original immutable scan context, current markers/config/keep rules, refreshed Git state, canonical roots and device/inode identity before cleanup. No new discoveries are added during clean. Dry-run exercises the same validation without creating backup sessions or changing files. Outside-HOME roots may be cleaned permanently, but backup mode rejects them with BACKUP_UNSUPPORTED_PATH; backup failure never falls back to deletion. Validated selected ancestors cover descendants once, while independently selectable scan rows remain available.

These checks reduce stale-result risk; they are not atomic with deletion, do not detect active builds, and cannot guarantee inactivity. Byte counts are logical estimates, including regular-file and symlink-entry sizes; they are not physical disk-block measurements.

Clean JSON and scan events

clean --json requires --all or --categories; actual cleanup also requires --yes. Dry-run does not. Stdout contains one versioned document, including empty and failed runs. Diagnostics go to stderr; JSON mode does not prompt or open a browser. Exit status is 0 for a complete scan/plan/clean (including empty), 1 for scan/config/validation/execution failure; invalid CLI usage follows Commander's nonzero convention.

Per-filesystem-item outcomes include category, path, status, estimated size and rejection/skip reasons. Statuses are deleted, backed-up, would-delete, would-back-up, rejected, or skipped. Covered children report SKIPPED_COVERED_BY_PARENT with zero duplicate accounting. External tools such as Docker and Homebrew have action-level outcomes, not invented filesystem deletion records.

Existing aggregate fields remain. Actual totalFreedSpace, totalBackedUpSize, and totalCleanedItems are separate from wouldFreeSpace, wouldBackUpSize, and wouldCleanItems; dry-run actual counters are zero. Scan JSON retains totalSize, totalItems, category fields and verbose item path/size, adding optional id, fileCount, newestEntryModifiedAt, and artifact evidence. IDs hash category plus NUL plus canonical path; they identify rows and do not authorize cleanup.

Library callers can pass onEvent and signal: AbortSignal to scanner options. Events are start, progress, candidate, warning, and done, correlated by runId and category where applicable. The registry shares one repository discovery pass per request. Cancellation returns no usable cleanup plan. The Promise API remains; repository callers pass scanResult.context as the additive fourth argument to clean(items, dryRun, backupDir, context). Bare repository cleanup without scan evidence is refused.

Live review requires a terminal and cannot be combined with JSON. Use s/m/p for size/newest-mtime/path sorting, / for search, n/b for pages, arrows to move, space to select, and q to cancel. Selection survives view changes. Enter during scanning cannot submit; after completion it finishes review before the ordinary final confirmation and validation. scan --live is read-only.

Uninstall Apps

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

npx mac-cleaner-cli uninstall

Maintenance Tasks

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

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

Backups (opt-in)

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.

Flags

-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

Troubleshooting

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.

💻 Global Installation

If you use this tool frequently:

npm install -g mac-cleaner-cli
mac-cleaner-cli

🔒 Security

✅ Open SourceAll code publicly available for audit
✅ No NetworkOperates 100% offline (only app install talks to GitHub, to download the app)
✅ No Root RequiredAll operations run as current user
✅ Minimal DepsOnly 5 runtime dependencies
✅ CI/CDEvery release tested with TypeScript, ESLint, and automated tests
✅ Socket.devDependencies 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

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)

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

  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.

💬 Community

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

Star History Chart

💚 Support

If this tool saved you time or disk space, consider supporting the project!

Support on Ko-fi

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