# How to Configure open_with for Custom File Extension Handlers in Superfile > Configure open_with in Superfile to handle custom file extensions. Map file extensions to shell commands in config.toml using %s for the file path. - Repository: [Yorukot/superfile](https://github.com/yorukot/superfile) - Tags: how-to-guide - Published: 2026-07-26 --- **Add an `[openwith]` table to your [`config.toml`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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: ```bash mkdir -p ~/.config/superfile cp /path/to/superfile/src/superfile_config/config.toml ~/.config/superfile/config.toml ``` ## Structuring the openwith Table Inside [`config.toml`](https://github.com/yorukot/superfile/blob/main/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. ```toml # ~/.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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/config.toml) to ensure every unlisted file type still opens with a sensible default. ```toml 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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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: ```toml # ~/.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: ```bash # 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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/pkg/utils/config_interface.go); entry point is [`src/main.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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.