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

> Safely preview destructive actions with Mole's dry-run mode. Set DRY_RUN=true to see changes before files are modified or deleted. Learn how to use this essential safety feature.

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

---

**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`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) at lines 28-30, the argument parser sets the dry-run state:

```bash
--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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/bin/purge.sh) at lines 244-246 and [`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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:

```bash

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

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

```bash
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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/bin/purge.sh)**: Processes the dry-run flag at lines 244-246 and conditionally skips destructive operations at lines 253-257.

- **[`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/clean.sh), [`uninstall.sh`](https://github.com/tw93/Mole/blob/main/uninstall.sh), [`purge.sh`](https://github.com/tw93/Mole/blob/main/purge.sh), and [`optimize.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) at lines 28-30, this sets `DRY_RUN=true` and exports `MOLE_DRY_RUN=1`, which child processes like [`uninstall.sh`](https://github.com/tw93/Mole/blob/main/uninstall.sh) and [`purge.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/core/help.sh) file documents the `--dry-run` flag for each of these commands, and the [`SECURITY_AUDIT.md`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) at lines 86-92, providing a persistent record for audit purposes before you run the command without the dry-run flag.