soap 🧼

"I was so lazy to use any GUI to clean my macOS." — @kud

A macOS CLI that removes an app and all its leftover files — preferences, caches, containers, launch agents, and more.

Inspired by AppCleaner and App Eraser, but open-source and terminal-native.

Install

npm install -g @kud/soap-cli

Or via Homebrew:

brew install kud/tap/soap-cli

Usage

soap <cask-name>        Clean an app installed via Homebrew cask
soap <path-to-app>      Clean a manually installed app
soap --help             Show this help

Examples:

soap spotify
soap android-studio
soap '/Applications/Android Studio.app'

What it does

Cask mode — soap spotify

1. Resolves the .app name from brew info
2. Scans ~40 macOS directories for files matching the app name or bundle identifier
3. Fetches the cask's zap stanza — the maintainer-curated list of known leftover files
4. Presents a checkbox list of everything found (all pre-selected)
5. Moves selected files to Trash (recoverable from ~/.Trash)
6. Optionally runs brew uninstall --zap to unregister the cask from Homebrew

Path mode — soap '/Applications/Spotify.app'

Same as above, but skips the Homebrew step. Use this for apps installed manually from a DMG.

Example output

Welcome to soap 🧼, the app cleaner.

⠋ Fetching cask info…
⠋ Scanning for files…

ℹ Cleaning: Spotify
ℹ Mode: cask (spotify)

? Found 11 files. Select what to move to Trash:
 ◉ /Users/kud/Library/Application Support/Spotify
 ◉ /Users/kud/Library/Caches/com.spotify.client
 ◉ /Users/kud/Library/Preferences/com.spotify.client.plist
 ◉ /Users/kud/Library/Saved Application State/com.spotify.client.savedState
 ◉ /Users/kud/Library/Logs/Spotify
 ◉ ...

? Run `brew uninstall --zap spotify`? Yes

✔ Moved 11 file(s) to Trash.

◼ Running Homebrew uninstall…
✔ Done.

Locations scanned

soap scans these directories, plus <vendor>/ subdirectories derived from the bundle ID:

| Location | What's typically there | | ----------------------------------- | ------------------------------- | | /Applications | The app bundle | | ~/Library/Application Support | App data | | ~/Library/Caches | Cached data | | ~/Library/Containers | Sandboxed app data | | ~/Library/Preferences | .plist config files | | ~/Library/Logs | App logs | | ~/Library/LaunchAgents | Per-user background services | | /Library/LaunchDaemons | System-wide background services | | ~/Library/HTTPStorages | HTTP caches | | ~/Library/Group Containers | Shared app-group data | | ~/Library/Saved Application State | Window state (.savedState) | | ~/Library/WebKit | WebKit storage | | /private/var/db/receipts | Package receipts | | /Library/Logs/DiagnosticReports | Crash reports | | /Library/Audio/Plug-Ins/HAL | Audio drivers | | ~/Downloads | Leftover .dmg files |

Debug mode

SOAP_DEBUG=1 soap spotify

Enables verbose shell output — shows every subprocess command that runs.

Safety

• Files are moved to Trash, not permanently deleted.
• You get a full checkbox list before anything is removed — deselect anything you want to keep.
• The Homebrew uninstall is a separate confirmation step.
• The force-uninstall fallback (for already-removed apps still registered in Homebrew) defaults to No.

Contributing

Built with TypeScript + ESM. Requires Node 20+.

git clone https://github.com/kud/soap-cli.git
cd soap-cli
npm install

npm run dev        # run from source via tsx
npm run build      # compile to dist/
npm run typecheck  # type-check without emitting
npm test           # vitest unit tests

Credits

Inspired by App Eraser and AppCleaner.