# How to Enable Debug Logging in Mole: A Complete Guide

> Enable debug logging in Mole easily by setting MO_DEBUG=1 or using the --debug flag. Access detailed logs at ${HOME}/Library/Logs/mole/mole_debug_session.log.

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

---

**Set the `MO_DEBUG` environment variable to `1` or pass the `--debug` flag to any Mole command to enable verbose logging to `${HOME}/Library/Logs/mole/mole_debug_session.log`.**

Mole is a macOS utility by tw93 designed for managing applications and system optimization. When troubleshooting issues or auditing operations, you may need to enable debug logging in Mole to capture detailed execution traces and system information.

## Understanding Mole's Debug Logging Architecture

### The MO_DEBUG Environment Variable

Mole's debug logging is controlled entirely by the **`MO_DEBUG`** environment variable. When this variable is set to `1`, the logging system activates verbose output mode. This design allows both manual environment configuration and automated flag handling through command wrappers.

### Central Logging Implementation in lib/core/log.sh

The core logging logic resides in **[`lib/core/log.sh`](https://github.com/tw93/Mole/blob/main/lib/core/log.sh)**. This file contains function definitions that check the debug state using conditional expressions like `if [[ "${MO_DEBUG:-}" == "1" ]]`.

Key functions affected by debug mode include:
- `log_info()` – Writes informational messages
- `log_success()` – Confirms successful operations
- `debug_log()` – Writes debug-specific entries
- `log_system_info()` – Dumps system details when the module loads

When `MO_DEBUG=1`, these functions write additional `[DEBUG]` entries to the session log file at `${HOME}/Library/Logs/mole/mole_debug_session.log`.

## How to Enable Debug Logging in Mole

### Method 1: Using the --debug Command Flag

Each top-level Mole command supports a `--debug` flag that automatically exports the environment variable. The argument parsers in command wrappers like [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh), [`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh), [`bin/installer.sh`](https://github.com/tw93/Mole/blob/main/bin/installer.sh), [`bin/purge.sh`](https://github.com/tw93/Mole/blob/main/bin/purge.sh), and [`bin/uninstall.sh`](https://github.com/tw93/Mole/blob/main/bin/uninstall.sh) contain this case statement:

```bash
"--debug")
    export MO_DEBUG=1
    ;;

```

To enable debug logging for a single operation:

```bash
mo clean --debug

```

This exports `MO_DEBUG=1` for the duration of that command only.

### Method 2: Setting the MO_DEBUG Environment Variable

For granular control, export the variable directly in your shell:

```bash
export MO_DEBUG=1
mo optimize

```

This approach persists for the entire shell session, affecting all subsequent Mole commands without requiring the `--debug` flag.

### Method 3: Persistent Debug Mode in Shell Sessions

To maintain debug logging across multiple terminal sessions, add the export to your shell configuration file:

```bash
echo 'export MO_DEBUG=1' >> ~/.zshrc

```

After reloading your configuration (`source ~/.zshrc`), every Mole command will automatically run in debug mode.

## What Gets Logged When Debug Mode Is Active

### System Information Dump

When [`lib/core/log.sh`](https://github.com/tw93/Mole/blob/main/lib/core/log.sh) loads with `MO_DEBUG=1`, the `log_system_info()` function executes immediately. This writes a header containing:
- macOS version
- Sudo status
- Shell environment details
- Timestamp markers

This header appears at `${HOME}/Library/Logs/mole/mole_debug_session.log` before any command-specific output.

### Operation Boundaries and Cache Removal Details

During command execution, debug mode captures:
- Function entry points (e.g., `=== start_cleanup ===`)
- Cache removal operations with specific byte counts
- File path resolutions
- Success/failure states for each sub-operation

Example log output:

```

[DEBUG] Debug session log saved to: /Users/you/Library/Logs/mole/mole_debug_session.log
[DEBUG] === start_cleanup ===
[DEBUG] Removing cache: /Users/you/Library/Caches/com.example.app (120.3MB)
[DEBUG] Operation completed successfully

```

## Viewing and Analyzing Debug Logs

To inspect the detailed execution trace:

```bash
less "${HOME}/Library/Logs/mole/mole_debug_session.log"

```

For real-time monitoring during command execution:

```bash
tail -f "${HOME}/Library/Logs/mole/mole_debug_session.log" &
mo clean --debug

```

To filter for specific operations:

```bash
grep "start_cleanup" "${HOME}/Library/Logs/mole/mole_debug_session.log"

```

## Summary

- **Debug logging in Mole** is controlled by setting `MO_DEBUG=1` as an environment variable.
- The **`--debug`** flag on any command (`mo clean --debug`, `mo optimize --debug`) automatically exports this variable.
- Central logging logic resides in **[`lib/core/log.sh`](https://github.com/tw93/Mole/blob/main/lib/core/log.sh)**, which checks `MO_DEBUG` and writes to `${HOME}/Library/Logs/mole/mole_debug_session.log`.
- When enabled, **`log_system_info()`** dumps system details immediately, and all operations write verbose `[DEBUG]` entries showing boundaries, file removals, and status changes.
- Command wrappers in **[`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh)**, **[`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh)**, and related files implement the `--debug` parsing.

## Frequently Asked Questions

### Where does Mole store its debug log files?

Mole writes debug logs to `${HOME}/Library/Logs/mole/mole_debug_session.log` on macOS. This path is hardcoded in [`lib/core/log.sh`](https://github.com/tw93/Mole/blob/main/lib/core/log.sh) and is created automatically when `MO_DEBUG=1` is set and any logging function executes.

### Can I enable debug logging for all Mole commands at once?

Yes. Export `MO_DEBUG=1` in your shell configuration file (e.g., `~/.zshrc` or `~/.bash_profile`). This persists the setting across all terminal sessions, ensuring every Mole command runs with debug logging enabled without requiring the `--debug` flag.

### Does the --debug flag work with every Mole subcommand?

Yes. The `--debug` flag is implemented consistently across all command wrappers including [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh), [`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh), [`bin/installer.sh`](https://github.com/tw93/Mole/blob/main/bin/installer.sh), [`bin/purge.sh`](https://github.com/tw93/Mole/blob/main/bin/purge.sh), and [`bin/uninstall.sh`](https://github.com/tw93/Mole/blob/main/bin/uninstall.sh). Each wrapper parses the flag and exports `MO_DEBUG=1` before executing the command logic.

### How do I disable debug logging once enabled?

If you set `MO_DEBUG` manually using `export MO_DEBUG=1`, run `unset MO_DEBUG` or close the terminal session. If you added the export to your shell configuration file, remove that line and run `source ~/.zshrc` (or equivalent) to reload the configuration. The `--debug` flag only affects the single command invocation, so subsequent commands run without debug logging unless the flag is passed again.