How to Enable Debug Mode and Troubleshoot Issues in Superfile

Superfile provides two primary debugging mechanisms: a persistent debug configuration flag in config.toml that activates verbose slog logging, and a --debug-info CLI flag for one-off diagnostic dumps without modifying configuration files.

When diagnosing unexpected behavior in the terminal file manager Superfile, developers and power users rely on structured logging and runtime diagnostics. According to the yorukot/superfile source code, the application exposes debugging capabilities through both a configuration toggle and command-line utilities. Understanding how to activate these features allows you to capture detailed internal state and validate system dependencies.

Enabling Debug Mode in Superfile

Superfile supports two distinct methods for accessing diagnostic information: persistent verbose logging via the configuration file, and temporary diagnostic dumps via CLI flags.

Configuration File Method

The primary method for sustained troubleshooting involves editing the TOML configuration file. In src/superfile_config/config.toml (lines 76-78), the debug field controls the logger's verbosity level.

When debug = true, the initialization logic in src/internal/config_function.go (lines 44-48) sets the global logger to slog.LevelDebug. This causes every slog.Debug call throughout the codebase—including UI updates, file panel operations, and zoxide queries—to be written to the log file.

To enable persistent debug mode:

1. Open your user configuration file (default: ~/.config/superfile/config.toml, located via spf path-list)

2. Set the debug flag:

   debug = true

3. Restart Superfile to apply the changes

Using the --debug-info CLI Flag

For immediate diagnostics without modifying configuration files, Superfile provides the --debug-info (or -d) flag defined in src/cmd/main.go (lines 84-89). This triggers the printDebugInfo function in src/cmd/debug_info.go (lines 38-41), which outputs a formatted report containing version information, OS details, environment variables, and dependency statuses.

spf --debug-info

# or

spf -d

This command displays critical paths (configuration file, log file) and checks for external dependencies like ffmpeg, exiftool, and zoxide that affect preview and navigation functionality.

Working with Debug Logs and System Diagnostics

Once debug mode is active, the log file becomes the primary resource for troubleshooting runtime issues.

Locating and Reading the Log File

Superfile writes timestamped log entries to a state directory. The exact path is available through the path-list command:

spf path-list

Typically located at ~/.local/state/superfile/superfile.log, this file contains all slog.Debug statements when debug mode is enabled. To monitor logs in real-time:

tail -f $(spf pl | awk '/Log file path/ {print $NF}')

Key debug sources to examine include:

• UI rendering decisions in src/internal/ui/filepanel/update.go
• Zoxide navigation queries in src/internal/ui/zoxide/model.go
• Metadata extraction initialization in src/internal/config_function.go

Validating External Dependencies

Many Superfile features rely on external binaries. The --debug-info output includes a "Dependencies" section that verifies the presence of:

• ffmpeg: Required for video previews
• exiftool: Used for metadata extraction
• zoxide: Powers intelligent directory jumping

If these tools are missing or not in PATH, related features will fail silently unless debug logging is enabled.

Reproducing Issues with Verbose Logging

To effectively troubleshoot:

1. Enable debug = true in your configuration
2. Clear or backup the existing log file to isolate new entries
3. Restart Superfile and reproduce the problematic behavior
4. Examine the log for slog.Debug entries surrounding the error condition

The debug output includes internal state such as panel updates, memory statistics from printRuntimeInfo, and exact call stacks leading to errors.

Summary

• Enable persistent debugging by setting debug = true in ~/.config/superfile/config.toml, which sets the logger to slog.LevelDebug as implemented in src/internal/config_function.go
• Use --debug-info (or -d) for immediate diagnostic dumps showing version, paths, and dependency statuses without configuration changes
• Monitor ~/.local/state/superfile/superfile.log (path available via spf path-list) to view timestamped debug entries from UI components, zoxide queries, and metadata operations
• Verify external dependencies (ffmpeg, exiftool, zoxide) using the diagnostic output to identify missing tools causing preview or navigation failures
• Restart Superfile after modifying configuration to ensure the logger initializes with the correct verbosity level

Frequently Asked Questions

Where is the Superfile log file located?

The log file resides in your user state directory, typically ~/.local/state/superfile/superfile.log. Run spf path-list (or spf pl) to display the exact path on your system, as this varies based on XDG environment variables and operating system conventions.

What is the difference between the config debug flag and --debug-info?

The debug configuration option enables persistent verbose logging to the log file by setting the internal logger to slog.LevelDebug, capturing all slog.Debug calls continuously. In contrast, --debug-info is a one-time CLI command that prints a static diagnostic dump to stdout and exits immediately, without modifying the logger state or configuration files.

Why are my debug logs not showing any verbose output?

If debug = true is set but you only see INFO-level messages, ensure you restarted Superfile after saving the configuration. The logger initialization occurs in src/internal/config_function.go during startup, reading common.Config.Debug to determine the appropriate slog level. Without a restart, the logger retains its previous configuration.

Does Superfile check for missing dependencies automatically?

Yes, the printDebugInfo function in src/cmd/debug_info.go explicitly checks for ffmpeg, exiftool, and zoxide binaries in your PATH. Running spf --debug-info reports whether these optional dependencies are found, helping diagnose why video previews or zoxide navigation might not function as expected.

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