# 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](#1-quick-start)
2. [Installation](#2-installation)
3. [The Interactive Menu](#3-the-interactive-menu)
4. [Everyday Commands](#4-everyday-commands)
   - [clean — Free up disk space](#41-clean--free-up-disk-space)
   - [uninstall — Remove apps completely](#42-uninstall--remove-apps-completely)
   - [optimize — Refresh caches and services](#43-optimize--refresh-caches-and-services)
   - [analyze — Explore disk usage](#44-analyze--explore-disk-usage)
   - [status — Monitor system health](#45-status--monitor-system-health)
   - [purge — Remove old project artifacts](#46-purge--remove-old-project-artifacts)
   - [installer — Find and remove installer files](#47-installer--find-and-remove-installer-files)
   - [history — Review past activity](#48-history--review-past-activity)
5. [Setup & Maintenance Commands](#5-setup--maintenance-commands)
   - [touchid — Touch ID for sudo](#51-touchid--touch-id-for-sudo)
   - [completion — Shell tab completion](#52-completion--shell-tab-completion)
   - [update — Update Mole](#53-update--update-mole)
   - [remove — Uninstall Mole itself](#54-remove--uninstall-mole-itself)
6. [Previewing Safely with `--dry-run`](#6-previewing-safely-with---dry-run)
7. [Scripting with JSON Output](#7-scripting-with-json-output)
8. [Quick Launchers (Raycast & Alfred)](#8-quick-launchers-raycast--alfred)
9. [How Mole Keeps You Safe](#9-how-mole-keeps-you-safe)
10. [Configuration & Environment Variables](#10-configuration--environment-variables)
11. [Troubleshooting](#11-troubleshooting)
12. [Frequently Asked Questions](#12-frequently-asked-questions)
13. [Command & Flag Reference](#13-command--flag-reference)

---

## 1. Quick Start

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

```bash
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:

```bash
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](#6-previewing-safely-with---dry-run).

---

## 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"

    ```bash
    brew install mole
    ```

=== "Install script"

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

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

| Executable | Purpose |
|------------|---------|
| `mole` | The full command name |
| `mo` | A convenience alias that runs `mole` |

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`:

```bash
# 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`](#53-update--update-mole) for switching channels later.

### 2.3 Verify the installation

```bash
mo --version
```

```text
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

| Tool | Required? | Used for |
|------|-----------|----------|
| macOS | **Required** | Mole is macOS-only |
| `curl` or `wget` | Required | Downloading updates and the installer |
| Homebrew (`brew`) | Optional | Homebrew installs and updates |
| `fd` | Recommended for `purge` | Faster project scanning (`brew install fd`) |
| `trash` CLI | Optional | Faster Trash moves during `uninstall` (falls back to Finder) |
| `gh` (GitHub CLI) | Optional | Verifies release build-provenance attestations |
| `go` toolchain | Optional | Building the helper binaries from source |

---

## 3. The Interactive Menu

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

```text
 __  __       _
|  \/  | ___ | | ___
| |\/| |/ _ \| |/ _ \
| |  | | (_) | |  __/   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
```

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move the selection |
| `1`–`5` | Jump directly to that tool |
| `Enter` | Launch the highlighted tool |
| `M` | Show the full help (all commands) |
| `V` | Show version and system info |
| `T` | Configure Touch ID (only shown when not yet enabled) |
| `U` | Update Mole (only shown when an update is available) |
| `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**.

```bash
mo clean
```

```text
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**

| Option | Description |
|--------|-------------|
| `--dry-run`, `-n` | Preview the cleanup without deleting anything |
| `--external PATH` | Clean macOS metadata (e.g. `.DS_Store`, `._*`) from a mounted external volume at `PATH` |
| `--whitelist` | Open the protected-paths manager so specific caches are never cleaned |
| `--debug` | Show detailed per-operation logs |
| `-h`, `--help` | Show command help |

**Examples**

```bash
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`](#42-uninstall--remove-apps-completely) 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.

```bash
mo uninstall
```

```text
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**

| Option | Description |
|--------|-------------|
| `--list` | List installed apps with the exact names `mo uninstall` accepts |
| `--dry-run`, `-n` | Preview the uninstall without removing anything |
| `--permanent` | Skip the macOS Trash and delete immediately with `rm -rf` |
| `--debug` | Show detailed per-operation logs |
| `-h`, `--help` | Show command help |

**Examples**

```bash
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.

```bash
mo optimize
```

```text
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**

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview the optimizations without applying them |
| `--whitelist` | Exclude specific optimizations (path patterns supported) |
| `--debug` | Show detailed per-operation logs |
| `-h`, `--help` | Show command help |

> [!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.

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

```text
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
```

| Key | Action |
|-----|--------|
| `↑ ↓ ← →` | Navigate the tree (enter/leave folders) |
| `O` | Open the selected item |
| `F` | Reveal the selected item in Finder |
| `⌫` (Delete) | Move the selected item to the Trash |
| `L` | Toggle the large-files view |
| `Q` | Quit |

**Options**

| Option | Description |
|--------|-------------|
| `--json` | Print the analysis as JSON instead of opening the UI |
| `-h`, `--help` | Show command help |

> [!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.

```bash
mo status
```

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

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

| Key | Action |
|-----|--------|
| `k` | Toggle the cat mascot (preference is saved) |
| `q` / `esc` / `Ctrl-C` | Quit |

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:

| Option | Default | Description |
|--------|---------|-------------|
| `--json` | off | Output a one-shot metrics snapshot as JSON and exit |
| `--proc-cpu-threshold N` | `100` | Alert when a process stays above `N`% CPU |
| `--proc-cpu-window DURATION` | `5m` | How long it must stay above the threshold (e.g. `30s`, `2m`) |
| `--proc-cpu-alerts=false` | enabled | Disable the high-CPU alert banner |

> [!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.

```bash
mo purge
```

```text
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**

| Option | Description |
|--------|-------------|
| `--paths` | Edit the list of directories to scan |
| `--dry-run`, `-n` | Preview the purge without deleting anything |
| `--include-empty` | Include empty artifact directories in the results |
| `--debug` | Show detailed per-operation logs |
| `-h`, `--help` | Show command help |

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

```text
~/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.

```bash
mo installer
```

```text
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**

| Option | Description |
|--------|-------------|
| `--dry-run`, `-n` | Preview the cleanup without deleting anything |
| `--debug` | Show detailed per-operation logs |
| `-h`, `--help` | Show command help |

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

```bash
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**

| Option | Description |
|--------|-------------|
| `--json` | Output history as JSON |
| `--limit N` | Show the most recent `N` entries (1–200; default 20) |
| `-h`, `--help` | Show command help |

> [!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).

```bash
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**

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview the change without modifying the sudo config |
| `-h`, `--help` | Show command help |

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

```bash
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.

```bash
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**

| Option | Description |
|--------|-------------|
| `--force`, `-f` | Reinstall even if you are already on the latest version |
| `--nightly` | Switch to / update the nightly (main-branch) build |

> [!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`.

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

**Options**

| Option | Description |
|--------|-------------|
| `--dry-run`, `-n` | Preview the removal without deleting anything |

---

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

```bash
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:

```bash
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:

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

```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:

```bash
mo status | jq '.health_score'
```

```text
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:

```bash
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:

| Location | Contents |
|----------|----------|
| `~/.config/mole/` | `install_channel`, `purge_paths`, `status_prefs`, `whitelist`, `whitelist_optimize`, plus the installed libraries and helper binaries |
| `~/.cache/mole/` | Update-check cache (`version_check`, `update_message`) |
| `~/Library/Logs/mole/` | `mole.log`, `operations.log`, `deletions.log` |

The user-facing environment variables:

| Variable | Effect |
|----------|--------|
| `NO_COLOR` | Any non-empty value disables ANSI colors (honors [no-color.org](https://no-color.org)) |
| `MO_NO_OPLOG=1` | Disable operation logging |
| `MO_DEBUG=1` | Enable verbose debug logging (same as `--debug`) |
| `MO_LAUNCHER_APP=<name>` | Override terminal auto-detection for quick launchers |
| `MO_ANALYZE_PATH=<path>` | Set the default target for `mo analyze` |
| `MOLE_REQUIRE_ATTESTATION=1` | Fail an update unless its build-provenance attestation verifies |
| `MOLE_VERSION=<token>` | Used by the installer to select `main`, `dev`, or a version tag |

---

## 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

| Command | Purpose | Key options |
|---------|---------|-------------|
| `mo` | Open the interactive menu | — |
| `mo clean` | Free up disk space | `--dry-run`/`-n`, `--external PATH`, `--whitelist`, `--debug` |
| `mo uninstall [APP…]` | Remove apps + leftovers | `--list`, `--dry-run`/`-n`, `--permanent`, `--debug` |
| `mo optimize` | Refresh caches & services | `--dry-run`, `--whitelist`, `--debug` |
| `mo analyze [PATH]` | Explore disk usage | `--json` |
| `mo status` | Live system dashboard | `--json`, `--proc-cpu-threshold N`, `--proc-cpu-window DUR`, `--proc-cpu-alerts=false` |
| `mo purge` | Remove project build artifacts | `--paths`, `--dry-run`/`-n`, `--include-empty`, `--debug` |
| `mo installer` | Find & remove installer files | `--dry-run`/`-n`, `--debug` |
| `mo history` | Review past activity | `--json`, `--limit N` |
| `mo touchid [enable\|disable\|status]` | Touch ID for sudo | `--dry-run` |
| `mo completion` | Shell tab completion | `--dry-run` |
| `mo update` | Update Mole | `--force`/`-f`, `--nightly` |
| `mo remove` | Uninstall Mole itself | `--dry-run`/`-n` |
| `mo --help` | Show all commands | — |
| `mo --version` | Show version & system info | — |

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

---

_Generated June 2026 from tw93/Mole at 470667c. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._