👋 Introduction

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

soap is 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.

It works with Homebrew casks and with apps installed manually from a DMG. Everything is moved to Trash by default, and you get a checkbox list of every file before anything is removed.

📦 Install

npm install -g @kud/soap-cli

Or via Homebrew:

brew install kud/tap/soap-cli

Requires macOS and Node 20+.

🚀 Quick start

Clean an app installed via a Homebrew cask:

soap spotify

Clean an app installed manually from a DMG, by path:

soap '/Applications/Slack.app'

soap then scans macOS for leftover files, shows you a pre-selected checkbox list, moves what you keep selected to Trash, and (for casks) offers to run brew uninstall --zap.

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
 ◉ ...

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

✔ Moved 11 file(s) to Trash.

👉 Next steps

• Usage — modes, flags, and examples.
• What gets removed — every location soap scans and how it finds leftovers.
• Safety — Trash, confirmations, and the root-owned file fallback.

🙏 Credits

Inspired by App Eraser and AppCleaner.