cleanmac

Links: npm · GitHub

Command-line tool to scan macOS for installed applications and related support files, helping you perform thorough manual uninstallations.

The CLI now emits JSON output and a tabular summary by default so it can be piped into other tooling while still remaining readable in a terminal. A live spinner reports progress while applications are being scanned.

Features

• Finds .app bundles in common system and user application directories.
• Collects related Library files (Application Support, Caches, Preferences, etc.).
• Outputs a concise report or JSON for automation.
• Designed to be executable via npx without global installs.

Usage

Install or invoke the published package from npm:

npx cleanmac scan
# shows spinner, table view, and JSON payload
npx cleanmac uninstall firefox               # moves app bundle to Trash + runs cleanup script (prompts for admin rights if needed)

During development, link or run locally:

bun install
bun run dev                          # defaults to `cleanmac scan`
bun run dev scan firefox             # JSON + table
bun run dev scan --no-table          # JSON only
bun run dev scan --no-json           # Table only

Commands

• cleanmac scan [query] – Scan for apps, optionally filtering by a text query.
  • --no-json – Disable the default JSON payload.
  • --no-table – Disable the default table view.
• cleanmac list – Alias for scan without filters (same options).
• cleanmac uninstall <query> – Move the matching app bundle to Trash and run a cleanup script for residual files (requests admin rights when needed).
  • --output <path> – Set a custom script path.
  • --force – Proceed even if multiple apps match (picks the first result).

Next steps

1. Add a removal helper that offers deletion commands.
2. Expand scanning to cover kexts, launch agents, and login items.