macleanup 5.3.0

macleanup 5.3.0

Desktop app

• Assistant: ask about a preview by typing or speaking (Speak). It sees section numbers, sizes and counts — never a file path or file name — and links the docs pages it used. Free 30 questions a month, Pro 300, Team 1,000.
• Receipt backups (Pro and Team): back up a receipt's summary to your account and restore it on another Mac. Backups hold numbers only, no paths.
• Required updates: the app checks for a release notice at start, every 15 minutes and when you come back. Automatic updates now install and relaunch at a quiet moment, never during a run.
• No more Apple Music, media or Photos prompts on a first preview.

Command line (npm 5.3.0)

• Section 26 (disk usage report) skips ~/Music, ~/Movies and ~/Pictures and says so.

Install: download macleanup.dmg (Apple silicon and Intel). The app is not notarized: the first time, open it from Applications, then System Settings › Privacy & Security › Open Anyway. Installed 5.2.x apps update in place.

macleanup 5.2.2

Desktop app 5.2.2

macleanup.dmg — Apple silicon and Intel, macOS 11 or later. Installed copies of 5.2.0 update themselves from inside the app.

• Paths you choose to keep are now left alone by every section.
• Scheduled runs report back with a receipt in History. If you created a schedule in 5.2.0, open Schedules and save it once more so it starts reporting.
• Sign-in, the Errors screen, keyboard shortcuts, the appearance shortcut and the data download were fixed.

First open of the unsigned app: System Settings → Privacy & Security → Open Anyway (once).

The command line

Fixed

• --exclude-path now keeps a path in every bulk wipe and age-based prune, not only in the per-item deletes. A folder that holds a kept path is left whole. In a preview, kept entries show as skip.
• Section 18 (large files report) no longer walks into photo libraries, iCloud folders, Movies, Music, virtual machines or the Trash; it skips them, which makes the scan seconds instead of minutes on a large home folder. Its top files are listed as report items in --json-events.

Changed

• The script is split into an entry file, macleanup.sh, and ordered modules in lib/, each under 500 lines. Behaviour is unchanged: --help, --list, --version and dry-run event streams were compared line for line against 5.2.1.
• Logs, reports, --contact and the run footer name the macleanup team and its website, docs and issues page. Personal phone, address and profile links are removed.

Run it with npx macleanup@5.2.2 · Full changelog

macleanup 5.2.0 — the desktop app

The macleanup desktop app

macleanup_5.2.0_universal.dmg — one disk image for Apple silicon and Intel Macs, macOS 11 or later. It runs the same macleanup.sh as npx macleanup, with a disk gauge, a dry-run ledger and a receipt for every run.

The first time you open it: macleanup is not signed with an Apple developer certificate yet. Open the disk image, drag macleanup into Applications, then open System Settings → Privacy & Security and choose Open Anyway. You do this once; later versions arrive through the app's own signed updater.

If you used the 4.6 desktop app: install 5.2.0 from this page once. The 4.6 app cannot update itself to 5.2.0.

The command line

Added

• Section 0 (system health, read-only) lists installed developer toolchains — Node versions under nvm, pyenv Pythons, rbenv Rubies, rustup toolchains, Java VMs, Xcode, the Android SDK and Studio, Docker Desktop, Flutter and Homebrew — with the space each takes. It changes nothing; each toolchain's own uninstaller removes it.
• --json-events: each item carries age_days (days since it was last opened or changed), and toolchain items carry tool and version. Both are additive; the schema stays at version 1.
• The macleanup desktop app for macOS ships with this release.

Run it with npx macleanup@5.2.0 · Full changelog

macleanup 5.1.0

Added

• --json-events: a newline-delimited JSON event stream on stdout — plan, disk (before and after, with the local-snapshot count), section_start, item, progress, section_result (completed, skipped or failed, with a reason), error and summary. Schema version 1 is documented in docs/json-events.md. The macleanup desktop app reads it.
• --archive-path PATH (repeatable): before PATH is deleted or moved to the Trash, it is written to a gzip archive in ~/.macleanup/archives/ (folder mode 700, file mode 600). If the archive cannot be written, PATH is left in place.
• Section 12 lists the orphan-shaped entries it skipped because they were touched recently, in its report, for review. A skipped entry is not proof that nothing is left behind.
• Section 25 lists loaded Homebrew and third-party services in both launchd domains (your user's and the system's). A brew services list run in one domain can say none while a root service is running.
• The session summary shows attempted, skipped and failed sections beside the completed ones, and the local-snapshot count with a note that deleted files may not free space until macOS releases those snapshots.

Changed

• --exclude-path now protects a path in every section's delete and Trash move, not only sections 23 and 24.
• --all runs its safe-batch sections through the same dispatcher as --only, so every run uses one accounting path.

Verified

• The launcher runs on Node 14.21.3, so the declared engines.node: ">=14" floor holds (ISSUE-003).

macleanup 5.0.0 — one name

Changed — one name: macleanup

The product, the command and every file it writes now use one name. Run it as macleanup or npx macleanup.

Before 5.0.0	From 5.0.0	What happens to the old name
mac-cleanup command	macleanup command	Removed. Use macleanup (it was already an alias).
mac-cleanup.sh	macleanup.sh	Renamed in the package and repository.
~/.mac-cleanup/ (logs, reports, history)	~/.macleanup/	Copied once on the first 5.x run, when ~/.macleanup/ does not exist yet. The old folder stays in place until you remove it.
~/.mac-cleanuprc	~/.macleanuprc	Still read when the new file is absent, with a note asking you to rename it.
MAC_CLEANUP_LOGS_DIR, MAC_CLEANUP_REPORTS_DIR, MAC_CLEANUP_RC	MACLEANUP_LOGS_DIR, MACLEANUP_REPORTS_DIR, MACLEANUP_RC	Still read for 5.x when the new variable is unset, with a deprecation note.
Daily log mac-cleanup-YYYY-MM-DD.log	macleanup-YYYY-MM-DD.log	New logs use the new name; copied logs keep theirs.

Removed

• The package main entry. require('macleanup') used to launch the cleanup tool as a side effect of importing it. macleanup has no programmatic API, so importing it now fails fast instead (ISSUE-004).

macleanup desktop 4.6.1

Patch release for the macleanup macOS app + CLI.

Install

1. Download macleanup_4.6.1_x64.dmg, open it, drag macleanup to Applications.
2. First launch (unsigned app): right-click → Open, then Open. One-time Gatekeeper step.

Fixed in 4.6.1

• Dry-run preview now shows a real estimate. It used to report 0 B because the preview never tallied a total; it now measures what each section would delete and shows the estimated space to free.
• Reports list shows only the current run's files (no leftovers from earlier runs the same day).

Notes

• Auto-update is enabled — installed 4.6.0 apps will update to 4.6.1 on launch.
• Intel-native; Apple Silicon via Rosetta. Unsigned (no Apple Developer ID yet) → one-time right-click → Open.

macleanup desktop 4.6.0

Native macOS app for macleanup (the safe-by-default cleanup CLI) — tiny (~6.5 MB), 28 sections, true dry-run preview.

Install

1. Download macleanup_4.6.0_x64.dmg, open it, and drag macleanup to Applications.
2. First launch (the app is unsigned): right-click the app → Open, then click Open in the dialog. This is a one-time Gatekeeper step.

New in 4.6.0

• The GUI now runs system-level cleanups (system caches, logs, periodic maintenance, DNS, Time Machine snapshots) with a single macOS admin-password prompt per run. Previews never prompt.
• Full Disk Access shortcut added in Settings.
• Dry-run never asks for a password.

Notes

• Runs natively on Intel; runs on Apple Silicon via Rosetta. A universal build is planned.
• Auto-update is enabled (this release ships the signed updater manifest).
• The app is unsigned (no Apple Developer ID yet) — hence the one-time right-click → Open.