Mole User Guide

Mole is a single-binary command-line toolkit that cleans, uninstalls, analyzes, optimizes, and monitors macOS — all from your terminal. It rolls the jobs you would normally spread across CleanMyMac, AppCleaner, DaisyDisk, and iStat Menus into one fast, safety-first tool. This guide covers everything you need to install Mole, use every command, and recover from common problems.

Note

Mole is built for macOS. An experimental Windows build lives on a separate windows branch, but the stable tool documented here targets macOS only.

Table of Contents

1. Quick Start
2. Installation
3. The Interactive Menu
4. Everyday Commands
   • clean — Free up disk space
   • uninstall — Remove apps completely
   • optimize — Refresh caches and services
   • analyze — Explore disk usage
   • status — Monitor system health
   • purge — Remove old project artifacts
   • installer — Find and remove installer files
   • history — Review past activity
5. Setup & Maintenance Commands
   • touchid — Touch ID for sudo
   • completion — Shell tab completion
   • update — Update Mole
   • remove — Uninstall Mole itself
6. Previewing Safely with --dry-run
7. Scripting with JSON Output
8. Quick Launchers (Raycast & Alfred)
9. How Mole Keeps You Safe
10. Configuration & Environment Variables
11. Troubleshooting
12. Frequently Asked Questions
13. Command & Flag Reference

1. Quick Start

Install Mole, then run it. The fastest path on most Macs:

brew install mole
mo

mo (a short alias for mole) with no arguments opens the interactive menu. From there you can reach the five most common tools with the arrow keys. If you prefer to jump straight to a task:

mo clean          # Reclaim disk space from caches, logs, and leftovers
mo uninstall      # Remove an app and everything it left behind
mo analyze        # Browse what is using your disk
mo status         # Live CPU / memory / disk / network dashboard
mo optimize       # Rebuild caches and refresh system services

Tip

Every destructive command supports --dry-run. Run mo clean --dry-run the first time to see exactly what would be removed without touching a single file. See Section 6.

2. Installation

Mole ships as a small bash CLI plus two compiled Go helper binaries (analyze and status). You can install it through Homebrew or with the official install script.

2.1 Install with Homebrew (recommended)

Homebrew

brew install mole

Install script

curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash

Both methods install two executables to /usr/local/bin:

Supporting libraries and the compiled helper binaries are placed under ~/.config/mole/.

2.2 Install a specific version or the bleeding edge

The install script accepts an optional version token. Pass it through the piped script using -s:

# Latest unreleased main-branch code ("edge"/nightly build)
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s latest

# A specific tagged release
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s 1.17.0

Note

latest and main install the nightly channel (newest main-branch commit). A bare version number such as 1.17.0 installs that exact tagged release on the stable channel. See mo update for switching channels later.

2.3 Verify the installation

mo --version

Mole version 1.42.0
macOS: 14.5
Architecture: arm64
Kernel: 23.5.0
SIP: Enabled
Disk Free: 223.5 GB
Install: Homebrew
Shell: /bin/zsh

If mo is not found, your install directory is not on PATH. The installer prints the exact export PATH=... line to add to your ~/.zshrc or ~/.bash_profile when this happens.

2.4 Requirements & optional tools

3. The Interactive Menu

Running mo with no arguments shows a banner and a five-item menu:

 __  __       _
|  \/  | ___ | | ___
| |\/| |/ _ \| |/ _ \
| |  | | (_) | |  __/   https://github.com/tw93/mole
|_|  |_|\___/|_|\___|   Deep clean and optimize your Mac.

  1. Clean        Free up disk space
  2. Uninstall    Remove apps completely
  3. Optimize     Refresh caches and services
  4. Analyze      Explore disk usage
  5. Status       Monitor system health

↑↓  |  Enter  |  M More  |  V Version  |  T TouchID  |  Q Quit

Tip

Mole supports both arrow keys and Vim-style navigation (h j k l) across its interactive screens.

4. Everyday Commands

4.1 clean — Free up disk space

mo clean removes regenerable junk: user and browser caches, developer tool caches (Xcode, Node, npm), system logs and temp files, the Trash, and leftover files from apps you have already uninstalled.

mo clean

Scanning cache directories...

  ✓ User app cache                                           45.2GB
  ✓ Browser cache (Chrome, Safari, Firefox)                  10.5GB
  ✓ Developer tools (Xcode, Node.js, npm)                    23.3GB
  ✓ System logs and temp files                                3.8GB
  ✓ App-specific cache (Spotify, Dropbox, Slack)              8.4GB
  ✓ Trash                                                    12.3GB

====================================================================
Space freed: 95.5GB | Free space now: 223.5GB
====================================================================

Options

Examples

mo clean --dry-run            # Preview everything that would be removed
mo clean --dry-run --debug    # Preview with full operation detail
mo clean --whitelist          # Manage caches that should be protected
mo clean --external /Volumes/MyDrive   # Strip OS cruft from an external disk

Important

Use mo clean for leftovers from apps that are already gone. To remove an app that is still installed plus its files, use mo uninstall instead.

Note

System caches require administrator rights. If you want a complete preview that includes those, prime your sudo session first: sudo -v && mo clean --dry-run.

4.2 uninstall — Remove apps completely

mo uninstall removes an application and the trail it leaves behind: launch agents, preferences, caches, logs, WebKit storage, cookies, containers, and more.

mo uninstall

Select Apps to Remove
═══════════════════════════
▶ ☑ Photoshop 2024            (4.2G) | Old
  ☐ IntelliJ IDEA             (2.8G) | Recent
  ☐ Premiere Pro              (3.4G) | Recent

Uninstalling: Photoshop 2024
  ✓ Removed application
  ✓ Cleaned 52 related files across 12 locations

====================================================================
Space freed: 12.8GB
====================================================================

Run it with no arguments for the interactive selector, or name one or more apps to remove them directly.

Options

Examples

mo uninstall                    # Open the interactive app selector
mo uninstall slack              # Uninstall Slack
mo uninstall slack zoom         # Uninstall Slack and Zoom together
mo uninstall --dry-run slack    # Preview removing Slack
mo uninstall --list             # See exactly what names are accepted

Caution

By default, removed files go to the macOS Trash so you can recover them. --permanent bypasses the Trash and deletes immediately — there is no undo. Use it only when you are certain.

Note

--whitelist is not supported for uninstall (you explicitly chose to remove the app). Whitelisting applies to clean and optimize.

4.3 optimize — Refresh caches and services

mo optimize runs system maintenance: rebuilding databases, resetting network services, refreshing Finder and Dock, clearing diagnostic and crash logs, removing swap files, and rebuilding Launch Services and the Spotlight index.

mo optimize

System: 5/32 GB RAM | 333/460 GB Disk (72%) | Uptime 6d

  ✓ Rebuild system databases and clear caches
  ✓ Reset network services
  ✓ Refresh Finder and Dock
  ✓ Clean diagnostic and crash logs
  ✓ Remove swap files and restart dynamic pager
  ✓ Rebuild launch services and spotlight index

====================================================================
System optimization completed
====================================================================

Options

Tip

mo optimize --whitelist accepts path patterns, so a long-lived mounted disk image such as /Volumes/mail can be kept from showing up as a detach candidate.

4.4 analyze — Explore disk usage

mo analyze opens an interactive disk-space explorer. It shows where your space is going as a ranked, bar-charted tree you can navigate, and lets you open or delete items in place. Deletions here go through Finder to the Trash, which makes it the safest way to do ad-hoc cleanup.

mo analyze              # Explore from a system overview
mo analyze ~/Documents  # Explore a specific folder
mo analyze /Volumes     # Explore external drives only

Analyze Disk  ~/Documents  |  Total: 156.8GB

 ▶  1. ███████████████████  48.2%  |  📁 Library      75.4GB  >6mo
    2. ██████████░░░░░░░░░  22.1%  |  📁 Downloads    34.6GB
    3. ████░░░░░░░░░░░░░░░  14.3%  |  📁 Movies       22.4GB

  ↑↓←→ Navigate  |  O Open  |  F Show  |  ⌫ Delete  |  L Large files  |  Q Quit

Options

Note

By default Mole skips external drives under /Volumes for a faster start. Pass an explicit path (e.g. mo analyze /Volumes) to inspect them. You can also set the target through the MO_ANALYZE_PATH environment variable.

4.5 status — Monitor system health

mo status is a live dashboard: an overall health score plus real-time CPU, GPU, memory, disk I/O, network, power, and top-process metrics. It refreshes once per second.

mo status

Mole Status  Health ● 92  MacBook Pro · M4 Pro · 32GB · macOS 14.5

⚙ CPU                                    ▦ Memory
Total   ████████████░░░░░░░  45.2%       Used    ███████████░░░░░░░  58.4%
▤ Disk                                   ⚡ Power
⇅ Network                                ▶ Processes

The health score blends CPU, memory, disk, temperature, and I/O load, with color-coded ranges.

High-CPU process alerts. When enabled, mo status shows a read-only banner for any process that stays above a CPU threshold for a sustained window. Tune or disable it:

Tip

mo status automatically switches to JSON when its output is piped (not a terminal), so mo status | jq '.health_score' just works without --json.

4.6 purge — Remove old project artifacts

mo purge finds and removes heavy, regenerable build directories across your projects — node_modules, target, .build, build, dist, venv, and similar — then lets you pick which to delete.

mo purge

Select Categories to Clean - 18.5GB (8 selected)

➤ ● my-react-app       3.2GB | node_modules
  ● rust-app           4.1GB | target
  ○ current-work       856MB | node_modules  | Recent
  ● django-api         2.3GB | venv

Options

Custom scan paths. Run mo purge --paths (or edit ~/.config/mole/purge_paths directly), one directory per line:

~/Documents/MyProjects
~/Work/ClientA
~/Work/ClientB

When custom paths are set, Mole scans only those. Otherwise it uses defaults such as ~/Projects, ~/GitHub, and ~/dev.

Warning

mo purge permanently deletes the selected artifacts. Review the selection carefully before confirming. Projects modified in the last 7 days are flagged and left unselected by default.

Tip

Install fd for much faster scanning: brew install fd.

4.7 installer — Find and remove installer files

mo installer locates large installer files (.dmg, .pkg, .iso, .xip, .zip) across Downloads, Desktop, Homebrew caches, iCloud, and Mail, labels each by source, and lets you remove them.

mo installer

Select Installers to Remove - 3.8GB (5 selected)

➤ ● Photoshop_2024.dmg     1.2GB | Downloads
  ● PyCharm_Pro.dmg        640.5MB | Homebrew
  ● Acrobat_Reader.dmg     220.4MB | Downloads

Options

4.8 history — Review past activity

Every destructive operation Mole performs is logged. mo history shows the recent record so you can audit what was removed.

mo history            # Most recent activity (20 entries by default)
mo history --limit 50 # Show the 50 most recent entries
mo history --json     # Machine-readable output

Options

Note

Operation logging is on by default and writes to ~/Library/Logs/mole/operations.log. Disable it by setting MO_NO_OPLOG=1. Uninstall/Trash deletions are additionally recorded in ~/Library/Logs/mole/deletions.log.

5. Setup & Maintenance Commands

5.1 touchid — Touch ID for sudo

mo touchid configures macOS so you can authorize sudo prompts (which several Mole commands need) with Touch ID instead of typing your password. It edits the PAM sudo configuration to add the pam_tid.so module (using /etc/pam.d/sudo_local on macOS Sonoma and later).

mo touchid           # Interactive menu
mo touchid enable    # Enable Touch ID for sudo
mo touchid disable   # Disable it
mo touchid status    # Show whether it is configured

Options

5.2 completion — Shell tab completion

mo completion sets up tab completion for mo/mole in your shell. It supports bash, zsh, and fish, completing both subcommands and their options.

mo completion              # Set up completion for your shell
mo completion --dry-run    # Preview the shell-config changes first

5.3 update — Update Mole

mo update upgrades Mole in place. It detects whether you installed via Homebrew or the script and uses the right mechanism automatically.

mo update             # Update to the latest stable release
mo update --force     # Force-reinstall the latest stable version
mo update --nightly   # Install the latest unreleased main-branch build

Options

Note

--nightly is only available for script installations. Homebrew installs follow stable releases — reinstall via the script if you want nightly builds. When a nightly update is available, Mole shows a notice like New nightly commit abc1234 available, run mo update --nightly.

5.4 remove — Uninstall Mole itself

mo remove detects every Mole installation (Homebrew and manual) and removes the binaries along with ~/.config/mole, ~/.cache/mole, and ~/Library/Logs/mole.

mo remove             # Remove Mole (asks for confirmation)
mo remove --dry-run   # Show exactly what would be removed

Options

6. Previewing Safely with --dry-run

The destructive commands — clean, uninstall, purge, installer, and remove — all support --dry-run. In dry-run mode Mole performs the full scan and prints exactly what it would remove, but deletes nothing.

mo clean --dry-run
mo uninstall --dry-run
mo purge --dry-run
mo installer --dry-run
mo remove --dry-run

Add --debug to any of them for the full, per-path operation log:

mo clean --dry-run --debug

optimize, completion, and touchid enable also accept --dry-run.

Tip

Make --dry-run your default first move on any new machine. Once you trust the selection, re-run without it.

7. Scripting with JSON Output

Two commands emit structured JSON for automation:

mo analyze --json ~/Documents
mo status --json

{
  "host": "MacBook-Pro",
  "health_score": 92,
  "cpu": { "usage": 45.2, "logical_cpu": 8 },
  "memory": { "total": 25769803776, "used": 15049334784, "used_percent": 58.4 },
  "disks": [ ],
  "uptime": "3d 12h 45m"
}

mo status also auto-detects a piped (non-terminal) output stream and switches to JSON on its own:

mo status | jq '.health_score'

92

mo history --json likewise gives you a machine-readable activity record.

8. Quick Launchers (Raycast & Alfred)

You can trigger Mole's main tools from Raycast or Alfred. Install the launcher script:

curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-launchers.sh | bash

This adds five commands: Mole Clean, Mole Uninstall, Mole Optimize, Mole Analyze, and Mole Status.

For Raycast, finish the one-time setup:

1. Open Raycast Settings (⌘ + ,)
2. Go to Extensions → Script Commands
3. Click Add Script Directory
4. Add the path ~/Library/Application Support/Raycast/script-commands
5. Run Reload Script Directories from Raycast
6. Search for Mole Clean (or clean, Mole Status, etc.) to launch

Note

Mole auto-detects your terminal app. iTerm2 has known compatibility issues; Kaku, Alacritty, kitty, WezTerm, Ghostty, and Warp work well. Override detection with MO_LAUNCHER_APP=<name>.

9. How Mole Keeps You Safe

Mole performs destructive local operations, so it is built around safety-first defaults. As a user, the practical guarantees are:

• Protected directories are never touched. System Settings, Control Center, Finder, Dock, Keychains, Mail, Contacts, Calendars, iCloud Drive, and a long list of app data (password managers, dev tools, VPN configs, audio plug-in licenses) are protected from cleanup.
• Path validation. Mole refuses to delete the filesystem root, system directories (/System, /usr, /bin, /etc, …), anything reached via .. path traversal, or paths containing control characters.
• Trash by default for uninstall. Removed app files go to the macOS Trash so you can restore them. Only --permanent bypasses this.
• mo analyze is the gentlest cleanup path — it moves items to the Trash through Finder rather than deleting directly.
• Everything destructive is logged to ~/Library/Logs/mole/ and reviewable with mo history.
• Verified updates. Release binaries are checked against a published SHA256SUMS file, and (when the gh CLI is available) against a Sigstore build-provenance attestation before installation.

Important

For the deepest cleans, macOS may require Full Disk Access for your terminal so Mole can see protected cache locations. If a clean reports many permission-denied skips, grant Full Disk Access to your terminal in System Settings → Privacy & Security.

10. Configuration & Environment Variables

Mole keeps its state in three predictable locations:

The user-facing environment variables:

11. Troubleshooting

Each entry below uses the format Error → Cause → Solution → Prevention.

Scan stalls on "Project artifacts" or a particular folder

• Cause: A very large directory tree, or a path that no longer exists, can make a scan appear frozen (see community issues #1053, #1049).
• Solution: Press q to quit and re-run. For purge, install fd (brew install fd) for far faster, more robust scanning.
• Prevention: Narrow the scope — e.g. mo analyze ~/Documents instead of a full-system scan, or configure specific mo purge --paths.

Error: protected path cannot be deleted

• Cause: You targeted a path on Mole's protection list (system component, Keychain, app data, etc.).
• Solution: This is intentional — Mole is refusing an unsafe delete. If you genuinely want to remove a still-installed app, use mo uninstall <app>.
• Prevention: Use mo analyze for ad-hoc removals of your own files; let clean/optimize handle system caches.

Error: du timeout / unable to measure directory size with fast methods

• Cause: Measuring an extremely large or slow (e.g. network/external) directory exceeded the internal timeout.
• Solution: Re-run; transient I/O pressure usually clears. For external volumes, scope the command to that volume.
• Prevention: Avoid running heavy scans while another disk-intensive task is in progress.

Uninstall fails or an app cannot be fully removed

• Cause: Some vendors require their own uninstaller, or files are protected by SIP/MDM (community issues #1052, #1028).
• Solution: Run mo uninstall --dry-run <app> to see what Mole plans to remove; follow the vendor's official uninstaller when prompted. Enable Touch ID / provide admin rights for protected files.
• Prevention: Keep Full Disk Access granted to your terminal so Mole can reach all of an app's files.

"sudo password prompt" seems skipped

• Cause: A reported edge case where the sudo prompt did not pause for input (#1059).
• Solution: Prime your sudo session first with sudo -v, then re-run the command. Configuring Touch ID (mo touchid enable) avoids password timing issues entirely.
• Prevention: Run sudo -v && mo clean when you know admin-only caches are involved.

Bundled analyzer binary not found (or status binary not found)

• Cause: The compiled analyze-go/status-go helper is missing from ~/.config/mole/bin.
• Solution: Run mo update to restore the binaries, or reinstall Mole.
• Prevention: Avoid manually deleting files under ~/.config/mole.

Authentication failed during a removal

• Cause: Incorrect credentials, or Touch ID is not set up.
• Solution: Mole suggests mo touchid to enable fingerprint auth; otherwise re-enter your password or restart your terminal.
• Prevention: Configure Touch ID once with mo touchid enable.

mo is not found after install

• Cause: The install directory is not on your PATH.
• Solution: Add the line the installer printed (e.g. export PATH="/usr/local/bin:$PATH") to ~/.zshrc or ~/.bash_profile, then open a new terminal.
• Prevention: Install to a directory already on PATH (the default /usr/local/bin usually is).

Temperature / fan / battery details missing in mo status

• Cause: Some sensors are unavailable on certain Mac models or require system_profiler data that did not return (community issues #1058, #1066).
• Solution: This is hardware-dependent; the rest of the dashboard continues to work.
• Prevention: None needed — Mole degrades gracefully when a sensor is unavailable.

12. Frequently Asked Questions

Q: What is the difference between mo and mole? They are the same program. mo is a short alias that simply runs mole. Use whichever you prefer.

Q: Is Mole free? Yes — the CLI documented here is free and open source under the MIT license. A separate paid native Mac app (Mole for Mac) exists with a graphical experience, but it is not required.

Q: Does Mole work on Linux or Windows? No. Mole targets macOS. An experimental Windows build exists on a separate branch but is not the supported tool.

Q: When should I use clean vs uninstall? Use uninstall when the app is still installed and you want it (and its files) gone. Use clean to sweep up leftovers from apps that are already removed, plus general caches and logs.

Q: Can I undo a cleanup? mo uninstall sends files to the Trash by default, so those are recoverable until you empty it. mo clean, mo purge, and mo installer remove regenerable files directly. Always run --dry-run first if you are unsure.

Q: How do I see what Mole removed? Run mo history (add --limit 200 for more, or --json for scripts). Logs live in ~/Library/Logs/mole/.

Q: How do I stop Mole from cleaning a specific cache? Run mo clean --whitelist (or mo optimize --whitelist) to add it to the protected list, stored in ~/.config/mole/whitelist.

Q: Does mo clean need administrator access? User-level caches do not. System caches do — run sudo -v first, or enable Touch ID, for a complete clean.

Q: How do I update Mole? mo update for stable, mo update --nightly for the newest main-branch build (script installs only).

Q: How do I completely remove Mole? mo remove deletes the binaries plus ~/.config/mole, ~/.cache/mole, and ~/Library/Logs/mole.

Q: Why are colors not showing? You likely have NO_COLOR set, or your terminal does not support ANSI. Unset NO_COLOR to restore colors.

Q: Can I script Mole? Yes — mo analyze --json, mo status --json (also auto-JSON when piped), and mo history --json give machine-readable output.

Q: My terminal misbehaves with Mole's UI. What should I use? iTerm2 has known issues. Kaku, Alacritty, kitty, WezTerm, Ghostty, and Warp are recommended.

13. Command & Flag Reference

Global flag: --debug enables detailed logging on any command that performs operations.