Mole Mac Cleanup CLI Safety

Using Mole from an agent

Mole (mo) cleans, uninstalls, analyzes, optimizes, and monitors a Mac. It is a real deletion tool operating on someone's live machine, so the way an agent uses it differs from the way a human does: never guess, never let a TUI decide, and never let a destructive command run without the user having seen the list.

The rules

1. Preview before you delete. Always. Every destructive command takes --dry-run. Run it, read the result, show the user what would go, and only then offer the real run. An agent that runs mo clean before mo clean --dry-run has skipped the only step the user can veto.
2. The user runs the destructive command, not you, unless they explicitly asked you to do it in the current turn. "Clean my Mac" is such an ask; "why is my disk full" is not.
3. Never parse a TUI frame. Interactive mo analyze and terminal-attached mo status are full-screen Go programs whose output is drawn, not printed. Use mo analyze --json, mo status --json, or mo status --watch instead.
4. Never invent flags. The command surface is small and listed here; if something is not on this page, run mo <command> --help and read it, do not assume a --yes or --force exists.
5. Protection is a whitelist, not an argument. If the user wants a cache kept, the answer is mo clean --whitelist, not a hand-rolled find. Never work around Mole's safety layer with raw rm.

What answers which question

Machine-readable surfaces

These five surfaces are the agent-facing API. Everything else is for humans.

Disk usage. mo analyze --json prints one JSON object: path, overview, total_size, total_files, large_files[], and entries[] of {name, path, size, is_dir, insight, cleanable, last_access}. size is bytes. insight: true marks an entry Mole considers noteworthy (a large iOS backup, a runaway cache) and is set only in overview mode. Pass a path to scope it: mo analyze --json ~/Library; the flag must come before the path because the Go flag parser stops at the first positional argument.

Cleanup history. mo history --json [--limit N] (N is 1-200) prints logs (paths of the operations and deletions logs), limit, per-run activity in sessions[], and structured deletion audit entries in deletions[]. Use the README history notes for session identity and attribution semantics. This is how you answer "did Mole delete my file" without guessing.

Installed apps. mo uninstall --list piped (stdout not a TTY) prints the app inventory as JSON: name, bundle id, uninstall name, path, size. This is how you find the exact <UNINSTALL NAME> argument without touching the selector TUI.

The dry-run path list. mo clean --dry-run prints a summary to the terminal and writes every candidate path to ~/.config/mole/clean-list.txt. Read that file to review the paths found by that dry-run. It is a preview snapshot, not an executable deletion plan: a later mo clean rescans and revalidates current candidates, so the two target sets can differ. This list is clean-only: mo purge --dry-run and mo installer --dry-run print their candidates to the terminal and write no file.

System status. mo status --json prints one metrics snapshot. It also switches to JSON automatically when stdout is not a TTY, but pass --json explicitly in scripts so intent stays obvious. mo status --watch --interval 1s emits one complete JSON object per line from a warm collector. Bound the watch duration or sample count and terminate it after collecting the evidence the user asked for; do not leave an unbounded monitor running in the background.