mac-cleaner-cli: A Terminal-Based Cleaner for macOS That Skips the Subscription
Free macOS CLI to clean disk space, caches, logs, Homebrew, Xcode. Open-source alternative to CleanMyMac.
At a glance
- What is it?
- mac-cleaner-cli is a free, open-source TypeScript tool that scans and cleans caches, logs, Homebrew leftovers, and Xcode DerivedData from the macOS terminal. It offers interactive selection, scripting modes, and a strict safety model, but its risky categories require deliberate opt-in.
- Who is it for?
- Adopt mac-cleaner-cli if you are a developer or power user who prefers terminal workflows, wants a free and auditable alternative to CleanMyMac, and can accept the responsibility of reviewing what it proposes to delete. Do not adopt it if you need a GUI, require root-level system optimization, or expect the tool to make safety decisions for you.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 29 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What It Solves and Who It Is For
mac-cleaner-cli addresses the recurring problem of a full macOS disk, specifically the accumulation of caches, logs, Homebrew download leftovers, Xcode DerivedData, and orphaned node_modules. The README positions it as a free, open-source alternative to CleanMyMac X, with no subscription and no telemetry. The target user is clearly someone comfortable with a terminal: the primary invocation is npx mac-cleaner-cli, and the tool offers a CI/CD friendly mode for scripts. It is not for users who want a polished graphical interface or who are unwilling to read output before deleting. The tool's design assumes a user who can understand what a category like dev-cache or homebrew means and can make an informed choice.
How the Scan and Clean Flow Works
The CLI follows a four-step flow: scan, show, select, clean. In interactive mode, it scans for cleanable files, displays them with sizes, lets the user select with checkboxes, and then deletes only the chosen items. The tool categorizes files into three risk levels: safe, moderate, and risky. Safe categories include trash, temp-files, browser-cache, homebrew, and docker. Moderate categories include system-cache, system-logs, dev-cache, and node-modules. Risky categories, which are hidden unless the user passes --risky, include downloads older than 30 days, iOS backups, mail attachments, duplicates, large files over 500MB, language files, and git-worktrees. The README states that risky categories are always skipped in non-interactive mode unless --unsafe is passed. That is a deliberate safety gate: the tool forces a conscious opt-in before touching anything that could cause data loss.
Getting It Running: Commands and Flags
The quickest start is npx mac-cleaner-cli, which requires no installation. For frequent use, the README suggests npm install -g mac-cleaner-cli and then running mac-cleaner-cli. Interactive mode supports navigation with arrow keys, space to select, 'a' for all, 'i' to invert, and Enter to submit. For automation, there are non-interactive commands: scan shows what can be cleaned, scan --json outputs machine-readable data, and clean --categories trash,browser-cache,homebrew --yes deletes without prompts. A dry-run flag, --dry-run, previews what would be deleted. The maintenance command offers --dns to flush DNS cache and --purgeable to free purgeable space. Configuration is managed via config --init and config --show. Backups are listed and cleaned with backup --list and backup --clean. The flags include -r for risky categories, -f to force the file picker, -A for absolute paths, and --no-progress to disable progress bars. All these are documented in the README, and they give a clear picture of a tool designed for both interactive and scripted use.
Safety by Default, But With Gaps
The tool's safety model is its strongest feature and also its most fragile. The README claims 'safe by default' because risky items are hidden unless --risky is used. In non-interactive mode, risky categories are skipped unless --unsafe is passed. That is a sensible design. However, the classification of what is 'safe' is arbitrary. For example, browser-cache is listed as safe, but clearing browser cache can log users out of sessions or slow down first page loads. Similarly, dev-cache includes Xcode DerivedData, which can be regenerated but may slow down the next build. The tool does not appear to offer a way to preview the exact files before deletion in non-interactive mode without --dry-run, and even then, the dry-run only shows categories, not individual file paths unless --verbose is used with scan. A user who blindly runs clean --all --yes could delete something they later regret. The README does not mention a confirmation prompt for --yes, so the guard is the user's own judgment.
Where It Falls Short: Limitations and Wrong Use Cases
The most obvious limitation is that it is macOS-only; the README points to a separate windows-cleaner-cli for Windows, so this tool is not cross-platform. Another limitation is that it runs as the current user without root, which means it cannot clean system-level caches that require sudo, and the maintenance DNS flush may require sudo separately. The README says 'no root required' for the cleaning operations, but that also means it cannot touch files owned by other users or system directories that accumulate junk. For a user with a deeply cluttered system drive, the tool may only scratch the surface. It is also the wrong tool for someone who wants a one-click solution with a GUI, because the interactive terminal interface, while functional, is not as discoverable as a windowed app. Finally, the risky category 'duplicates' keeps the newest file, which is a heuristic that can fail: if the newest file is corrupted, the tool would keep the wrong one. There is no mention of a hash-based verification beyond that simple rule.
Comparison to CleanMyMac X and DaisyDisk
The README includes a comparison table that positions mac-cleaner-cli against CleanMyMac X and DaisyDisk. CleanMyMac X costs $39.95 per year, has telemetry, and offers a GUI. DaisyDisk is a one-time $9.99 purchase, also with telemetry, and focuses on disk visualization rather than cleaning. mac-cleaner-cli is free, open-source, has no telemetry, and works via terminal. The key difference in approach is that CleanMyMac and DaisyDisk are visual tools that let you see disk usage in a graphical map, which helps users understand what is taking space before deciding to delete. mac-cleaner-cli provides a list with sizes, but it does not offer a visual map. For a user who wants to explore disk usage interactively, DaisyDisk is the better fit. For a user who wants automated cleaning in a script, mac-cleaner-cli is the only one of the three that offers a JSON output and a --yes flag. The trade-off is between visual exploration and scriptable automation.
Maintenance, Upgrades, and License
The project is under the MIT license, which permits free use, modification, and distribution, including for commercial purposes, with attribution. The repository shows recent releases at v1.3.5, v1.3.4, and v1.3.3, all on the same day, suggesting active development. The README states that every release is tested with TypeScript, ESLint, and automated tests, and dependencies are monitored via Socket.dev for supply chain attacks. However, the maintenance cost for a user is the need to keep the tool updated, especially since it is distributed via npm and npx will fetch the latest version each time, which could introduce changes. There is a backup command, but the README does not specify what is backed up or how to restore it; the backup --list and backup --clean commands suggest that backups are created before deletion, but the exact mechanism is not documented in the provided material. Users should verify the backup behavior before relying on it.
Editorial conclusion
Adopt mac-cleaner-cli if you are a developer or power user who prefers terminal workflows, wants a free and auditable alternative to CleanMyMac, and can accept the responsibility of reviewing what it proposes to delete. Do not adopt it if you need a GUI, require root-level system optimization, or expect the tool to make safety decisions for you. Before first use, verify the current npm package version and review the source for any changes, especially around the risky categories, because the tool's value depends entirely on your trust in its file classification and deletion logic.
Community notes