# What Commands Are Available in Mole? Complete CLI Reference

> Explore all 13 Mole CLI commands with this comprehensive reference. Learn how to clean, uninstall, optimize, analyze, and manage your system effectively using the `mo` wrapper.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: api-reference
- Published: 2026-03-20

---

**Mole exposes 13 system maintenance commands through the `mo` wrapper, including `clean`, `uninstall`, `optimize`, `analyze`, `status`, `purge`, `installer`, `touchid`, `completion`, `update`, `remove`, `help`, and `version`, all defined in the `MOLE_COMMANDS` array in [`lib/core/commands.sh`](https://github.com/tw93/Mole/blob/main/lib/core/commands.sh).**

Mole is an open-source macOS maintenance toolkit that provides a unified command-line interface for system cleanup, disk analysis, and configuration management. All commands available in Mole are catalogued in a central Bash array and executed through a lightweight dispatcher architecture that routes calls from the `mo` wrapper to specialized implementation scripts.

## The 13 Mole CLI Commands

The complete command catalogue lives in **[`lib/core/commands.sh`](https://github.com/tw93/Mole/blob/main/lib/core/commands.sh)** where the `MOLE_COMMANDS` array pairs each command name with its description. This array powers the help system, tab completion, and the main entry point at **`bin/mole`**.

### System Cleanup and Maintenance

**`clean`** – Frees up disk space by scanning and deleting user and system caches, logs, and temporary files. Supports `--dry-run` for safe previews and `--whitelist` for protected path exclusions. Implemented in **[`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh)**.

**`uninstall`** – Provides an interactive TUI for selecting and completely removing applications along with their support files, launch agents, and preferences. Core logic resides in **[`bin/uninstall.sh`](https://github.com/tw93/Mole/blob/main/bin/uninstall.sh)**.

**`optimize`** – Performs deep system maintenance including rebuilding indexes, clearing system logs, restarting services, and refreshing caches. Found in **[`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh)**.

**`purge`** – Targets development artifacts by finding and deleting old `node_modules`, `target`, `build`, and `dist` directories across project folders. Supports dry-run mode. Implementation in **[`bin/purge.sh`](https://github.com/tw93/Mole/blob/main/bin/purge.sh)**.

### Disk Analysis and Monitoring

**`analyze`** – Launches an interactive TUI-driven disk usage explorer similar to `ncdu`, with optional `--json` output for scripting integration. Source at **[`bin/analyze.sh`](https://github.com/tw93/Mole/blob/main/bin/analyze.sh)**.

**`status`** – Displays a live dashboard of CPU, memory, disk, network, GPU, and power metrics. Automatically outputs JSON when piped to other commands. Located in **[`bin/status.sh`](https://github.com/tw93/Mole/blob/main/bin/status.sh)**.

**`installer`** – Searches common download locations for large installer packages (`.dmg`, `.pkg`, `.zip`) and offers batch removal with dry-run support. Code in **[`bin/installer.sh`](https://github.com/tw93/Mole/blob/main/bin/installer.sh)**.

### System Configuration and Setup

**`touchid`** – Configures Touch ID authentication for `sudo` commands, including status checks and dry-run capabilities. Implementation in **[`bin/touchid.sh`](https://github.com/tw93/Mole/blob/main/bin/touchid.sh)**.

**`completion`** – Installs shell tab-completion scripts for Bash, Zsh, and Fish by reading the `MOLE_COMMANDS` array. Found in **[`bin/completion.sh`](https://github.com/tw93/Mole/blob/main/bin/completion.sh)**.

### Utility and Maintenance Commands

**`update`** – Pulls the latest stable release (or specific tags/nightly builds) from GitHub and installs them. Generated at install time in **[`bin/update.sh`](https://github.com/tw93/Mole/blob/main/bin/update.sh)**.

**`remove`** – Completely uninstalls Mole itself, removing the binary, configuration files, launchers, and helper scripts. Implemented in **[`bin/remove.sh`](https://github.com/tw93/Mole/blob/main/bin/remove.sh)**.

**`help`** – Displays usage information for any top-level command by delegating to per-command help functions in **[`lib/core/help.sh`](https://github.com/tw93/Mole/blob/main/lib/core/help.sh)**.

**`version`** – Shows the current Mole version read from the `VERSION` constant. Wrapper script at **[`bin/version.sh`](https://github.com/tw93/Mole/blob/main/bin/version.sh)**.

## How Mole Routes Commands

### The Dispatcher Architecture

Commands are routed through **`bin/mole`**, which parses the first positional argument and validates it against the `MOLE_COMMANDS` array. Upon validation, it `exec`s the matching implementation script from the `bin/` directory.

The lightweight **`mo`** wrapper (8 lines in the repository root) simply forwards all arguments to `bin/mole`:

```bash
#!/bin/bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
exec "$SCRIPT_DIR/mole" "$@"

```

### Command Discovery and Completion

The centralized `MOLE_COMMANDS` array enables synchronized documentation and auto-completion:

1. **Help Generation** – The `show_help()` function iterates over `MOLE_COMMANDS` to print command descriptions
2. **Tab Completion** – [`lib/core/completion.sh`](https://github.com/tw93/Mole/blob/main/lib/core/completion.sh) reads the same array to provide candidates for Bash, Zsh, and Fish

This architecture ensures that adding a new command requires only appending to `MOLE_COMMANDS` and creating the corresponding script in `bin/`.

## Practical Usage Examples

All examples assume the `mo` wrapper is in your `$PATH`:

```bash

# List all available commands

mo --help

# Clean with dry-run preview

mo clean --dry-run

# Interactive app uninstallation

mo uninstall

# Check system health with JSON output

mo status --json | jq '.cpu.usage'

# Find large installers safely

mo installer --dry-run

# Enable Touch ID for sudo

mo touchid enable

# Install shell completions

mo completion zsh

# Update to latest version

mo update

# Remove Mole completely

mo remove

```

## Summary

- **Thirteen core commands** are available in Mole, ranging from system cleanup (`clean`, `purge`) to hardware monitoring (`status`) and configuration (`touchid`, `completion`)
- **Centralized catalogue** – The `MOLE_COMMANDS` array in [`lib/core/commands.sh`](https://github.com/tw93/Mole/blob/main/lib/core/commands.sh) serves as the single source of truth for command discovery, help text, and tab completion
- **Dispatcher pattern** – The `mo` wrapper forwards to `bin/mole`, which validates commands against `MOLE_COMMANDS` and executes the appropriate script from `bin/`
- **Consistent interface** – All commands support `--help`, and many support `--dry-run` for safe operation preview
- **Extensible architecture** – New commands are added by updating the central array and creating a corresponding script in `bin/`

## Frequently Asked Questions

### How do I see all available commands in Mole?

Run `mo --help` or `mo help` to display the complete command list. The help system reads from the `MOLE_COMMANDS` array defined in [`lib/core/commands.sh`](https://github.com/tw93/Mole/blob/main/lib/core/commands.sh), ensuring the output always matches the installed version's capabilities.

### Where are Mole command implementations stored?

Each command has a dedicated implementation script in the `bin/` directory (e.g., [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh), [`bin/analyze.sh`](https://github.com/tw93/Mole/blob/main/bin/analyze.sh)). The main dispatcher at `bin/mole` validates your input against the `MOLE_COMMANDS` catalogue and executes the corresponding script.

### Can I preview what a command will do before executing it?

Yes. Most destructive commands including `clean`, `purge`, and `installer` support the `--dry-run` flag. This flag performs a scan and reports what would be deleted without actually removing any files, allowing you to verify actions before execution.

### How do I add Touch ID support for sudo using Mole?

Execute `mo touchid enable` to configure Touch ID authentication for `sudo` commands. The `touchid` command (implemented in [`bin/touchid.sh`](https://github.com/tw93/Mole/blob/main/bin/touchid.sh)) modifies the necessary PAM configuration and includes a `status` sub-command to verify current settings.