garbageman-cli

garbageman is a minimal, safe, permission-aware CLI for reclaiming disk space on macOS.

It is dry-run by default, never deletes outside explicit allowlists, and skips protected categories gracefully when Full Disk Access is missing.

Features

• Dry-run by default
• Interactive --clean mode with per-group or per-item confirmation
• Category filtering with --only and --skip
• --verbose dry-run output that lists every deletion candidate path
• JSON output for scripting
• Hard safety boundary around approved cleanup roots
• Full Disk Access guidance for protected categories
• Universal macOS release packaging for GitHub Releases and Homebrew

Install

Homebrew

brew tap yunusemreyakisan/tap
brew install garbageman

Homebrew installs are binary-only and follow the latest published GitHub release asset.

If another tap or formula named garbageman ever conflicts locally, install it explicitly with:

brew install yunusemreyakisan/tap/garbageman

Manual Build

swift build -c release
cp .build/release/garbageman /usr/local/bin/garbageman

Usage

garbageman
garbageman --summary
garbageman --verbose
garbageman --clean
garbageman --clean --only caches,trash,brew
garbageman --clean --skip xcode,docker
garbageman --clean --yes-safe --only caches,npm,brew
garbageman --clean --downloads-older-than 60
garbageman --clean --keep-last-archives 5
garbageman --json

Categories

• caches: user cache directories inside ~/Library/Caches
• logs: user-space logs inside ~/Library/Logs
• trash: user Trash contents inside ~/.Trash
• xcode: DerivedData plus old archives, keeping the newest --keep-last-archives entries
• simulators: iOS Simulator devices, grouped and confirmed per runtime
• brew: brew --cache
• npm: ~/.npm/_cacache
• pip: ~/Library/Caches/pip
• yarn: ~/Library/Caches/Yarn
• gradle: ~/.gradle/caches
• pods: ~/Library/Caches/CocoaPods
• android: Android emulator snapshot directories under ~/.android/avd/*/snapshots
• docker: untagged dangling Docker images only
• downloads: direct files in ~/Downloads older than --downloads-older-than, confirmed per file
• ios-backups: Finder/iTunes backups in ~/Library/Application Support/MobileSync/Backup, confirmed per backup

Permissions

• Full Disk Access is only requested when protected categories such as ios-backups need it.
• If access is missing, garbageman prints guidance, offers to open System Settings, and continues with accessible categories.
• Regular user-owned locations such as caches, logs, Trash, and package-manager caches do not require special permissions.

Safety

• No deletion happens unless --clean is set.
• Every filesystem deletion target must be inside an approved root for its category.
• Category root directories themselves are never deleted; only discovered contents inside them are eligible.
• Protected paths such as /System, /Applications, ~/Documents, ~/Desktop, ~/Library/Preferences, ~/Library/Keychains, and iCloud Drive are always rejected.
• Docker cleanup is limited to dangling images; volumes are intentionally out of scope.

Release Flow

git push origin stable
git tag v1.0.2
git push origin v1.0.2

• Pushes and pull requests run CI on GitHub Actions.
• Before tagging, make sure the HOMEBREW_TAP_TOKEN repository secret is configured in yunusemreyakisan/garbageman with write access to yunusemreyakisan/homebrew-tap.
• A semver tag such as v1.0.2 publishes a universal macOS release asset on GitHub.
• Homebrew availability for a version starts only after that release asset exists.
• The release workflow updates yunusemreyakisan/homebrew-tap after publishing the GitHub release.
• The tap repo validates the formula on pushes and pull requests so Homebrew installs stay healthy.

License

MIT