How to Configure open_with for Custom File Extension Handlers in Superfile

Add an [openwith] table to your config.toml file that maps file extensions to shell commands, using %s as a placeholder for the target file path.

Superfile is a terminal-based file manager written in Go that allows users to define custom external applications for opening files based on their extensions. By editing the openwith configuration table in the TOML config file, you can override the default xdg-open behavior and launch specific viewers or editors for any file type. This guide explains the exact syntax and source-code implementation used in the yorukot/superfile repository.

Locating the Configuration File

Superfile reads its settings from a config.toml file stored in your XDG configuration directory (typically ~/.config/superfile/config.toml). The repository provides a template at src/superfile_config/config.toml that demonstrates the available options, including the [openwith] section.

If the file does not exist, copy the template from the repository root:

mkdir -p ~/.config/superfile
cp /path/to/superfile/src/superfile_config/config.toml ~/.config/superfile/config.toml

Structuring the openwith Table

Inside config.toml, create a table named [openwith]. Each key must be a quoted file extension (including the leading dot), and each value is a shell command string. The command must contain %s, which Superfile replaces at runtime with the absolute path of the selected file.

# ~/.config/superfile/config.toml

[openwith]
".pdf"  = "zathura %s"
".md"   = "code --new-window %s"
".png"  = "feh %s"
".txt"  = "vim %s"
".html" = "firefox --private-window %s"

Changes take effect immediately upon restarting Superfile. The application loads this mapping during initialization via the configuration interface defined in src/pkg/utils/config_interface.go.

Setting a Global Fallback with default_opener

When a file's extension is not present in the [openwith] table, Superfile falls back to the default_opener setting. Define this at the root level of config.toml to ensure every unlisted file type still opens with a sensible default.

default_opener = "xdg-open %s"

This fallback behavior is processed in the same configuration loading routine, ensuring that the default_opener string is used whenever a specific extension key is missing from the map.

Implementation Details in the Source Code

The configuration parsing logic resides in src/pkg/utils/config_interface.go, where the TOML decoder unmarshals the [openwith] table into a map structure accessible to the core application. The main entry point in src/main.go initializes this configuration before rendering the UI, binding the "open" action (typically triggered by pressing Enter on a file) to the appropriate command string.

When you press Enter on a file, Superfile looks up the extension in the loaded map, substitutes %s with the file's absolute path, and executes the resulting shell command via the system's process spawner.

Practical Examples

Below is a complete configuration example that handles documents, images, and archives, while falling back to xdg-open for everything else:

# ~/.config/superfile/config.toml

[openwith]
".pdf"   = "zathura %s"
".epub"  = "ebook-viewer %s"
".md"    = "nvim %s"
".jpg"   = "imv %s"
".png"   = "imv %s"
".zip"   = "file-roller %s"

default_opener = "xdg-open %s"

After saving the file, restart Superfile to load the new handlers:

# Kill any running instance and relaunch

killall superfile
superfile

Navigate to a file with a configured extension and press Enter; the specified application will launch with the file path automatically appended.

Summary

• Configuration file: Edit ~/.config/superfile/config.toml (template at src/superfile_config/config.toml).
• Table name: Use [openwith] to define extension-specific handlers.
• Placeholder: Include %s in each command where the file path should appear.
• Fallback: Set default_opener for file types not explicitly listed.
• Source locations: Loading logic is in src/pkg/utils/config_interface.go; entry point is src/main.go.

Frequently Asked Questions

What is the exact syntax for the openwith table in superfile?

The table must be named [openwith] in lowercase. Keys are quoted extensions like ".pdf" and values are command strings containing %s. For example: ".pdf" = "zathura %s". The TOML parser in src/pkg/utils/config_interface.go unmarshals this into a map used at runtime.

How do I specify the file path in the open command?

Use the literal string %s as a placeholder. When you press Enter on a file, Superfile replaces %s with the absolute path of that file before executing the shell command. Do not quote %s inside the command string unless your shell requires it.

Where does superfile look for the config.toml file?

Superfile follows the XDG Base Directory Specification and looks for config.toml in $XDG_CONFIG_HOME/superfile/, defaulting to ~/.config/superfile/config.toml if the variable is unset. The repository template at src/superfile_config/config.toml can be copied to this location as a starting point.

What happens if a file extension is not listed in openwith?

If an extension is missing from the [openwith] table, Superfile uses the value of default_opener defined at the top level of config.toml. If default_opener is also unset, the behavior depends on the operating system's default application associations, though setting an explicit fallback is recommended.

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