Skip to content

armgit / peel

Public Imported from GitHub
0

Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.

11.4 KB
Raw Blame
.\" "Generated by swift-argument-parser"
.Dd October 28, 2026
.Dt PEEL 1
.Os
.Sh NAME
.Nm peel
.Nd "Find what apps leave behind and move it to the Trash."
.Sh SYNOPSIS
.Nm
.Ar subcommand
.Op Fl -version
.Op Fl -help
.Sh DESCRIPTION
Peel only moves files to the Trash, so you can put them back. Items that need administrator access are left for the Peel app, which says how to remove in Finder those its helper may not move, and the tool refuses to run with sudo. History, the record of refusals, and the exclusions are in ~/Library/Application Support/Peel, shared with the Peel app, and in JSON a size Peel couldn't measure is null. The tool writes English whatever the Mac's language, since scripts read what it prints. Exit status: 0 when it did what was asked, 1 when something failed or stayed where it was (for `peel updates`, when no check got an answer), or History couldn't record what moved, 2 when you answered no, and 64 when the command or its options are wrong, or when Peel would have to ask and can't (add --yes).
.Bl -tag -width 6n
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.It Em apps
List installed apps.
.Bl -tag -width 6n
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em inventory
Write out what is installed and where each app came from.
.Pp
A Brewfile only lists what Homebrew can install again; everything else would be a line that doesn't work.
.Bl -tag -width 6n
.It Fl -format Ar format
What to write. Without it, text.
.Pp
.Bl -tag -width 6n
.It Ar text
A line per app, with its version and where it came from
.It Ar json
Every detail, for scripts
.It Ar csv
A table for a spreadsheet
.It Ar brewfile
What Homebrew can install again, for `brew bundle`
.El
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em leftovers
Show the files an app leaves behind.
.Pp
APP can be the path to the app, its bundle identifier, or its name. A bundle in the current folder is written ./Name.app.
.Bl -tag -width 6n
.It Ar app
The app to inspect.
.It Fl -all
Include files that need review before removing them.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em uninstall
Move an app and its leftovers to the Trash.
.Pp
Only leftovers Peel suggests are included. Items that need administrator access stay where they are: the Peel app moves those its helper may move, and once the app is in the Trash, Orphaned Files in the Peel app lists the rest under Needs an Administrator, with how to remove them in Finder.
The app itself moves first, so nothing of it goes to the Trash while it stays installed. Answering no exits with code 2; a removal that couldn't finish exits 1, and so does a privacy reset that didn't happen.
.Bl -tag -width 6n
.It Ar app
The app to remove: its path, bundle identifier, or name. Write ./Name.app for a bundle in the current folder.
.It Fl -keep-leftovers
Move only the app, not its leftovers.
.It Fl -reset-privacy
Also reset the app's privacy permissions, just before it moves, so it asks again if you reinstall it. The Trash can't bring them back.
.It Fl -dry-run
Show what would move without moving anything.
.It Fl -keep-in-dock
Leave the app's icon in the Dock. Without it, the icon comes out once the app is in the Trash, and goes back where it was if the app is put back.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em orphans
List files left by apps that are no longer installed, and move a group to the Trash.
.Pp
Nothing here is selected for you, so --remove takes the identifier of one group. What Peel refuses to move, what it leaves for you to choose in the app, and what needs administrator access, stays. What only an administrator can move is listed apart, with how to remove it in Finder.
.Bl -tag -width 6n
.It Ar group
The group to move, as `peel orphans` names it in its first column.
.It Fl -remove
Move the named group to the Trash, leaving out what Peel holds back.
.It Fl -dry-run
Show what would go without moving anything.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em history
List what Peel moved to the Trash.
.Pp
The same History the Peel app shows, written by both. Put a removal back with `peel restore`. With --refused, lists what Peel was asked to move and wouldn't, which nothing else keeps.
.Bl -tag -width 6n
.It Fl -limit Ar limit
Show at most this many removals. Without it, 20.
.It Fl -refused
List what stayed and why, instead of what moved.
.It Fl -clear
Move the record of every refusal to the Trash. Only with --refused.
.It Fl y , -yes
Don't ask for confirmation. Only with --clear.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em restore
Put a removal back where it came from.
.Pp
ID is what `peel history` shows in its first column; the first few characters are enough.
Items that need administrator access are left for the Peel app. Answering no exits with code 2; a restore that couldn't finish exits 1.
.Bl -tag -width 6n
.It Ar id
The removal to put back.
.It Fl -dry-run
Show what would go back without moving anything.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em exclusions
Show and change what Peel leaves alone.
.Pp
The same list the Peel app keeps. Nothing excluded is offered or moved by either, though an excluded app is still listed. Without a subcommand, it shows the list.
.Bl -tag -width 6n
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.It Em list
Show what Peel leaves alone.
.Bl -tag -width 6n
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em add
Leave a file, a folder, or an app alone.
.Pp
The startup disk, a folder at its top, your home folder, or its Library is refused: excluding one would leave every tool with nothing to show.
.Bl -tag -width 6n
.It Ar paths...
Files or folders to leave alone.
.It Fl -app Ar app
An app to leave alone: its path, bundle identifier, or name. Write ./Name.app for a bundle in the current folder.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em remove
Stop leaving something alone.
.Bl -tag -width 6n
.It Ar paths...
Files or folders to stop leaving alone.
.It Fl -app Ar app
An app to stop leaving alone: its path, bundle identifier, or name. Write ./Name.app for a bundle in the current folder.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.El
.It Em caches
List caches of developer tools, and move them to the Trash.
.Pp
With --remove, only what Peel would suggest goes: never a toolchain, an account, a token, or something it couldn't measure. Name tools to narrow it down.
.Bl -tag -width 6n
.It Ar tools...
Tools to look at, as `peel caches` names them. All of them when none is given.
.It Fl -remove
Move what Peel suggests to the Trash.
.It Fl -dry-run
Show what would go without moving anything.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em projects
List what builds left behind in your projects, and move it to the Trash.
.Pp
A folder only counts when the file that makes it sits beside it, its tool tagged it as a cache, or what it holds could only be its tool's, as with Python's __pycache__. Projects changed in the last 7 days or whose last change Peel couldn't tell, folders under a name that could mean anything, environments and installed packages, and folders Peel holds back, such as one Git tracks or one with a repository or a key inside, are listed but never suggested, and --remove moves only what is suggested.
.Bl -tag -width 6n
.It Ar folders...
Folders your projects live in.
.It Fl -remove
Move what Peel suggests to the Trash.
.It Fl -dry-run
Show what would go without moving anything.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em duplicates
Find folders and files with identical contents.
.Pp
Without folders, Peel scans Desktop, Documents, Downloads, Pictures, Movies, and Music. The first copy of each group is the one Peel suggests keeping. A copy in a folder that syncs to your other devices, such as iCloud Drive, is listed as one that stays and is never moved, and so is a copy with Finder tags, a Finder comment, or a resource fork the others lack, which keeps the bytes for them, so the others can all go. A folder is a copy of another only when every file under it matches, so what a folder already speaks for isn't listed again on its own.
.Bl -tag -width 6n
.It Ar folders...
Folders to scan.
.It Fl -kind Ar kind
Only files of this kind.
.Pp
.Bl -tag -width 6n
.It Ar documents
Text files, PDFs, and other documents, not source code
.It Ar images
Pictures and photos
.It Ar movies
Videos
.It Ar audio
Music and other sound
.It Ar archives
Zip files and other archives
.It Ar disk-images
Disk images, such as .dmg files
.El
.It Fl -min-size Ar min-size
Only files at least this large, and folders holding at least this much, like 500KB or 1.5GB, or 0 for every size. Without it, 100KB, as in the Peel app.
.It Fl -remove
Move what Peel suggests to the Trash.
.It Fl -dry-run
Show what would go without moving anything.
.It Fl y , -yes
Don't ask for confirmation.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em search
Search the Spotlight index for files.
.Pp
Peel asks Spotlight, so it finds only what Spotlight indexes, and network volumes aren't searched. It lists files alone, yours first, then those an app keeps in a Library folder, each largest first, at most 2000, and it says how many it left out and why.
.Bl -tag -width 6n
.It Fl -name Ar name
Part of the file name.
.It Fl -kind Ar kind
The kind of file.
.Pp
.Bl -tag -width 6n
.It Ar documents
Text files, PDFs, and other documents, not source code
.It Ar images
Pictures and photos
.It Ar movies
Videos
.It Ar audio
Music and other sound
.It Ar archives
Zip files and other archives
.It Ar disk-images
Disk images, such as .dmg files
.El
.It Fl -min-size Ar min-size
Only files at least this large, like 500KB or 1.5GB.
.It Fl -older-than Ar older-than
Only files not modified in this many days.
.It Fl -everywhere
Search every disk on this Mac, not only your home folder. Network volumes aren't searched.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em updates
Check installed apps for updates.
.Pp
Peel reads the settings of the Peel app: which source it prefers, which apps it was told to leave alone, which versions were skipped, and what its checks found before. Nothing is installed. Only apps with an update or a check that failed are listed unless --all is given.
.Bl -tag -width 6n
.It Fl -all
Show every app, not only those with an update.
.It Fl -json
Print JSON instead of text.
.It Fl -version
Show the version.
.It Fl h , -help
Show help information.
.El
.It Em help
Show subcommand help information.
.Bl -tag -width 6n
.It Ar subcommands...
.It Fl -version
Show the version.
.El
.El
.Sh "EXIT STATUS"
.Ex -std