Mole Dry-Run Mode: How to Preview Destructive Actions Safely

Mole's dry-run mode is a safety feature that lets you preview every destructive action before any files are actually removed or modified by setting DRY_RUN=true via the --dry-run or -n flag.

The tw93/Mole repository provides a macOS system maintenance toolkit that includes a robust Mole dry-run mode for safe operation verification. This feature ensures you can inspect exactly which files, caches, and applications would be affected by cleanup operations before any actual deletion occurs.

What Is Mole Dry-Run Mode?

Mole dry-run mode transforms every destructive operation into a no-op while preserving all discovery and validation logic. When activated, the tool performs complete path resolution, size calculation, and dependency checking, but instead of executing rm -rf or other mutating commands, it records the intended targets to a preview log at ~/.config/mole/clean-list.txt.

How Mole Dry-Run Mode Works

Flag Initialization and Environment Variables

In bin/clean.sh at lines 28-30, the argument parser sets the dry-run state:

--dry-run | -n) DRY_RUN=true; export MOLE_DRY_RUN=1 ;;

This exports the MOLE_DRY_RUN=1 environment variable, which all subsidiary scripts check before executing destructive operations. The bin/uninstall.sh script at lines 26-28 validates this flag using [[ "${MOLE_DRY_RUN:-0}" == "1" ]] to conditionally skip actual removal commands. Similarly, bin/purge.sh at lines 244-246 and bin/optimize.sh at lines 99-103 implement identical guards to ensure consistent safety across all destructive workflows.

Module-Level Protection and Target Registration

Each cleanup module respects the DRY_RUN flag by invoking register_dry_run_cleanup_target() instead of immediate deletion. In bin/clean.sh at lines 41-53, this function records the path, calculated size, and cleanup category to a structured list. The implementation writes these preview targets to ~/.config/mole/clean-list.txt at lines 86-92, creating a human-readable audit trail of what would have been removed.

User Feedback and Safety Banners

When dry-run mode is active, Mole prints explicit console banners to prevent operator confusion. In bin/uninstall.sh at lines 48-52, the script outputs: DRY RUN MODE, No app files or settings will be modified. The cleanup command generates a summary block at termination (lines 11-17) listing total paths affected, aggregate size reclaimed, and item counts without performing any filesystem mutations.

How to Use Mole Dry-Run Mode

Basic Preview Commands

Activate dry-run mode by appending --dry-run or the short -n flag to any destructive command:

# Preview user cache and log cleanup without deletion

mo clean --dry-run

# Preview application uninstallation

mo uninstall --dry-run

# Preview project build artifact removal

mo purge --dry-run

# Preview system optimization steps

mo optimize --dry-run

Combining with Debug Output

For scripting and auditing purposes, combine dry-run with the debug flag to view the exact commands that would execute:

mo clean --dry-run --debug

Setting MO_DEBUG=1 alongside MOLE_DRY_RUN=1 prints the precise shell commands to standard output without invoking them, enabling detailed workflow verification before production execution.

Integration with Whitelist Protection

Verify which protected paths are excluded from cleanup by combining dry-run with whitelist flags:

mo clean --dry-run --whitelist

This combination displays the intersection of your configured whitelist rules against the discovered cleanup targets, confirming that critical directories remain protected even in actual execution scenarios.

Implementation Across the Codebase

The dry-run architecture spans multiple core files in the tw93/Mole repository:

• bin/clean.sh: Implements register_dry_run_cleanup_target() at lines 41-53 and handles the --dry-run | -n argument parsing at lines 28-31. Exports the preview list to ~/.config/mole/clean-list.txt at lines 86-92.

• bin/uninstall.sh: Checks the MOLE_DRY_RUN environment variable at lines 26-28 and prints the dry-run banner at lines 48-52 to alert users that no modifications will occur.

• bin/purge.sh: Processes the dry-run flag at lines 244-246 and conditionally skips destructive operations at lines 253-257.

• bin/optimize.sh: Handles dry-run parameters at lines 99-103 and appends summary notes at line 149 indicating preview status.

• lib/core/help.sh: Documents the --dry-run flag for every command in the help system, including clean (lines 8-13), installer (lines 20-23), and uninstall (lines 60-65).

• SECURITY_AUDIT.md: Cites dry-run mode at lines 22-27 as a primary safety control for previewing destructive operations before execution.

Summary

• Mole dry-run mode prevents all file modifications by converting destructive commands into preview operations.
• The --dry-run or -n flag sets DRY_RUN=true and exports MOLE_DRY_RUN=1 for cross-script consistency.
• All modules check the environment variable before executing rm -rf or similar operations.
• Preview data is recorded to ~/.config/mole/clean-list.txt via register_dry_run_cleanup_target().
• Combine with --debug to inspect exact commands without execution risk.
• Implemented consistently across clean.sh, uninstall.sh, purge.sh, and optimize.sh.

Frequently Asked Questions

What files does Mole dry-run mode actually modify?

Mole dry-run mode modifies no files during execution. It only writes a preview summary to ~/.config/mole/clean-list.txt and outputs human-readable reports to the console. According to the source code in bin/clean.sh, the register_dry_run_cleanup_target() function records paths that would be removed, but all actual rm -rf calls are bypassed when MOLE_DRY_RUN equals 1.

How do I enable dry-run mode in Mole scripts?

Enable dry-run mode by passing the --dry-run or -n flag to any Mole command. In bin/clean.sh at lines 28-30, this sets DRY_RUN=true and exports MOLE_DRY_RUN=1, which child processes like uninstall.sh and purge.sh detect at lines 26-28 and 244-246 respectively. You can also manually export MOLE_DRY_RUN=1 before running Mole commands.

Can I use dry-run mode with all Mole commands?

Yes, dry-run mode is implemented across all destructive commands including mo clean, mo uninstall, mo purge, and mo optimize. The lib/core/help.sh file documents the --dry-run flag for each of these commands, and the SECURITY_AUDIT.md at lines 22-27 identifies it as a universal safety mechanism for the entire toolkit.

Where does Mole store the dry-run preview list?

Mole writes the dry-run preview list to ~/.config/mole/clean-list.txt during cleanup operations. This file contains the paths, sizes, and categories of all items that would be removed in an actual execution. The export occurs in bin/clean.sh at lines 86-92, providing a persistent record for audit purposes before you run the command without the dry-run flag.

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