What Commands Are Available in Mole? Complete CLI Reference

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.

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

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.

optimize – Performs deep system maintenance including rebuilding indexes, clearing system logs, restarting services, and refreshing caches. Found in 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.

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.

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.

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.

System Configuration and Setup

touchid – Configures Touch ID authentication for sudo commands, including status checks and dry-run capabilities. Implementation in 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.

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.

remove – Completely uninstalls Mole itself, removing the binary, configuration files, launchers, and helper scripts. Implemented in bin/remove.sh.

help – Displays usage information for any top-level command by delegating to per-command help functions in lib/core/help.sh.

version – Shows the current Mole version read from the VERSION constant. Wrapper script at 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 execs 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:

#!/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 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:

# 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 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, 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, 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) modifies the necessary PAM configuration and includes a status sub-command to verify current settings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}