mac-cleaner-cli: a free terminal cleaner for macOS disk space

What mac-cleaner-cli removes, and who it is built for

The repository describes itself as a way to "Free up disk space on macOS with a single command", removing caches, logs, Homebrew leftovers, Xcode DerivedData and junk files. It targets people who already live in a terminal: developers whose machines fill with npm, yarn, pip, CocoaPods and Xcode DerivedData, and anyone who wants disk cleanup inside a script rather than behind a GUI. The README positions it as an open-source alternative to CleanMyMac, and its comparison table lists the differences it cares about: price, telemetry, terminal operation and CI/CD friendliness.

The category list is the real product surface. Safe categories cover trash, temp-files, browser-cache, homebrew and docker. Moderate categories cover system-cache, system-logs, dev-cache and node-modules. Risky categories (downloads older than 30 days, ios-backups, mail-attachments, duplicates, large-files, language-files, git-worktrees) are hidden unless you pass --risky. That three-tier split is a design decision worth noticing: the tool does not decide for you what is junk, it decides what is allowed to appear in the menu.

How the scan, selection and clean flow actually works

The default invocation is interactive. The README states the CLI scans for cleanable files, shows what was found with sizes, lets you select what to clean, and deletes only the selection. Selection is done with checkboxes, and on supported categories the right-arrow key drills into individual folders and files. The navigation keys are documented as up/down to move, left to go back, right to enter, space to select, a for all, i to invert and Enter to submit. Supported categories for file-level drilling are user cache files, temporary files, system log files, development cache, browser cache and Homebrew cache.

Non-interactive use splits the same pipeline into two commands. scan reports what could be removed without deleting anything, and clean takes an explicit category list. That separation is what makes the tool usable in automation: a scan can be inspected or logged, then a clean can run against a fixed list. The README states risky categories are always skipped in non-interactive mode unless you pass --unsafe, which is a different flag from the --risky used in interactive mode. Two flags, two modes, similar names: read the usage section before wiring either into a script.

Install and first run with npx mac-cleaner-cli

There is no install step for a first look. The Quick Start section gives a single command, and the package is published on npm as mac-cleaner-cli.

npx mac-cleaner-cli

Running it opens the interactive scan. You should see a list of categories with sizes, checkboxes beside them, and the key hints for navigation. Nothing is deleted until you submit a selection.

If you use it often, the README also documents a global install. Note that package.json sets os to darwin and engines.node to a minimum of 20.12, so this will not install on Linux or Windows.

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

For a scripted first run, start with a scan and machine-readable output before deleting anything.

npx mac-cleaner-cli scan --json
npx mac-cleaner-cli scan --json --verbose

The README states that --verbose includes item paths, which is what you need to check whether a path you care about has been classified as cleanable. Then preview a clean against named categories.

npx mac-cleaner-cli clean --categories dev-cache --dry-run
npx mac-cleaner-cli clean --categories trash,browser-cache,homebrew --yes

The --dry-run flag previews without deleting, and --yes removes the confirmation prompt. The README presents these as suitable for cron and CI. Two other command groups exist: uninstall removes an app with its preferences, caches and support files, and maintenance --dns flushes the DNS cache (the README notes this may require sudo) while maintenance --purgeable frees purgeable space.

Where mac-cleaner-cli is the wrong tool

The clearest gap is rollback. The README lists a backup command group with backup --list and backup --clean, but it does not document a restore command, and it does not explain what the backup contains or where it lives. If your reason for wanting a cleaner is the safety net a commercial tool advertises, this project's documentation does not give you one you can verify. Treat deletion here as final until you have read the source.

The second gap is platform. package.json declares os: darwin, so the tool is macOS-only by construction. The README points Windows users at a separate project, windows-cleaner-cli, rather than claiming portability.

The third is judgement. The tool reports sizes and lets you pick; it does not tell you whether a given cache is safe to remove for your workload. The safe and moderate tables name categories, not paths, so a directory you rely on could sit inside a category the README calls generally safe. The --risky flag is a gate on visibility, not a guarantee about the items behind it. If you want a tool that decides for you, this is not it.

mac-cleaner-cli compared with DaisyDisk and CleanMyMac

The README's own comparison table sets mac-cleaner-cli against CleanMyMac X and DaisyDisk. The stated differences: mac-cleaner-cli is free, open source, has no telemetry, runs in a terminal and is CI/CD friendly, while CleanMyMac X is listed at $39.95/year and DaisyDisk at $9.99 one-time, with both marked as closed source and carrying analytics. DaisyDisk is also marked as lacking an app uninstaller.

The approaches differ in kind, not just in price. DaisyDisk is a visual disk map: you find large files by looking at a picture of your disk. mac-cleaner-cli is a category scanner: it knows where caches, logs and build artifacts conventionally live and offers those as a list. That means mac-cleaner-cli is fast on the well-known paths and blind to anything outside its category definitions, while a disk-map tool shows you everything and leaves the interpretation to you. A reasonable setup is to use both, since they answer different questions. The README does not claim mac-cleaner-cli finds large files outside its large-files category, which is gated behind --risky.

Maintenance cost, licence and dependency surface

The last push to the repository was on 2026-06-09, and the most recent release listed is v1.3.5 on the same date. That is roughly three months before today, so the project is not stale by the six-month measure, but it is also not a repository with daily activity. The release history shows three versions (v1.3.3, v1.3.4, v1.3.5) published within about half an hour of each other on that date, which looks like a single release session rather than a steady cadence. Plan for a tool that moves in bursts.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and it is compatible with forking, which the README explicitly invites. It says nothing about warranty, and MIT licences typically disclaim it; if you are deploying this across a fleet, that is a question for your own legal review, not something this article can settle.

The dependency surface is small and worth stating precisely. package.json lists five runtime dependencies: @inquirer/checkbox, @inquirer/confirm, chalk, commander and ora. The README describes them as coming from trusted maintainers and mentions Socket.dev monitoring for supply chain attacks. Development uses bun for install and dev, tsdown for the build, vitest for tests and eslint for lint, so contributing requires a bun toolchain even though the published artifact runs on Node 20.12 or later.

Security posture and what the README does not say

The security section makes four claims: the code is open source and auditable, the tool operates 100% offline, no root is required because operations run as the current user, and dependencies are minimal. It also states every release is tested with TypeScript, ESLint and automated tests, and points vulnerability reports at GitHub Security Advisories. The offline claim is the one that matters most for adoption, because it means the cleaner has no channel to send file paths anywhere. You can verify it the same way you verify any npm package: read the source, or run it with network access blocked.

What the README does not cover is equally relevant. It does not document rollback, as noted. It does not describe how categories map to concrete filesystem paths outside the --verbose scan output. It does not state which macOS versions are supported, only that the package targets darwin. And the maintenance --dns command is flagged as possibly needing sudo, which is the one place where the no-root claim meets an exception. None of these are defects in the tool; they are limits on what you can learn before running it.

Editorial conclusion

Adopt mac-cleaner-cli if you want a scriptable, offline cleaner that fits cron or CI and you are comfortable reviewing a category list before deleting. Do not adopt it if you need undo: the README documents a backup command group but never explains how to restore from it. Before the first real run, execute npx mac-cleaner-cli scan --json and read the item paths, then run the same categories with --dry-run. Verify how your own ~/Library/Caches paths are classified, because the README's safe and moderate tables do not list individual paths.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes