How to Use Superfile for File Organization: A Complete Guide to Terminal File Management

Superfile is a keyboard-driven terminal file manager written in Go that organizes files through a dual-pane interface, supporting copy, move, rename, delete, and batch operations via vim-style shortcuts without leaving the command line.

Superfile is a modern, open-source file manager located in the yorukot/superfile repository. Built on the Bubble Tea framework, it combines the classic two-panel layout of Midnight Commander with contemporary customization options, allowing you to manipulate directory structures and streamline workflows directly from the shell using the Bubble Tea Update/View cycle.

Installation and Quick Start

To begin organizing files with Superfile, install the binary using the official auto-install scripts.

For macOS and Linux systems, execute:

bash -c "$(curl -sLo- https://superfile.dev/install.sh)"

Windows users can run the PowerShell alternative:

powershell -ExecutionPolicy Bypass -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://superfile.dev/install.ps1'))"

Once installed, launch the application by typing spf in your terminal. This command initializes the Bubble Tea event loop defined in src/cmd/main.go, which parses command-line flags, loads the embedded configuration from main.go, and renders the dual-pane interface.

Understanding Superfile's Architecture

Superfile follows a modular architecture centered on the Bubble Tea Model-Update-View pattern. The entry point in main.go embeds default configurations using //go:embed directives and delegates execution to the command runner.

The core components include:

• src/cmd/main.go: Parses CLI flags and constructs the top-level Bubble Tea program, injecting the embedded filesystem configuration.
• src/internal/model.go: Implements the tea.Model interface, maintaining global application state including active panels, current directory paths, and selection metadata.
• src/internal/config_function.go: Handles configuration merging, reading user-provided JSON or TOML files and overlaying them onto embedded defaults.
• src/internal/ui/sidebar/sidebar.go: Renders the dual-panel layout and processes panel-specific input events.
• src/internal/handle_file_operations.go: Contains the implementation logic for copy, move, delete, rename, and directory creation operations.

This architecture ensures that file organization commands propagate through a centralized state management system in src/internal/model.go before executing filesystem operations.

File Organization Workflows

Navigating the Dual-Pane Interface

Superfile uses vim-style navigation keys to move between directories and panels:

• j and k: Move the cursor down and up within the active panel.
• h and l: Switch focus between the left and right panels.
• Enter: Open the selected directory or execute the selected file.
• Tab: Toggle between file list view and preview mode.
• q: Quit the application.
• ?: Display the help overlay showing all available keybindings.

These shortcuts are processed by the main event loop in src/internal/model.go and rendered by components in src/internal/ui/.

Performing File Operations

Organize your filesystem efficiently using these single-key commands, all implemented in src/internal/handle_file_operations.go:

• Rename: Press r, type the new filename, and press Enter.
• Delete: Press d to move selected items to the system trash (OS-dependent).
• Copy: Press c to copy the highlighted item to the opposite panel's directory.
• Move: Press m to move the selected item to the opposite panel's location.
• Create Directory: Press a (for add), enter the directory name, and confirm.

Each operation triggers validation and execution logic within src/internal/handle_file_operations.go, which handles path resolution and conflict checking.

Customization and Configuration

Modifying Keybindings

Customize your workflow by editing the hotkey configuration. The default vim-style mappings are stored in src/superfile_config/vimHotkeys.toml. Create a custom TOML file in your user configuration directory (typically ~/.config/superfile/) to override specific bindings. The src/internal/config_function.go file handles merging these user preferences with embedded defaults during the startup sequence.

Theming and Plugins

Superfile supports visual customization through theme files placed in src/config/theme/. Reference your custom theme in ~/.config/superfile/config.toml.

For extended functionality, Superfile can load external binaries that adhere to a JSON IPC contract, allowing you to integrate specialized file organization tools or cloud sync utilities directly into the interface.

Programmatic Integration

Developers can embed Superfile functionality into Go applications. To launch Superfile with a custom embedded configuration:

package main

import (
    "embed"
    "github.com/yorukot/superfile/src/cmd"
)

//go:embed myconfig/*
var custom embed.FS

func main() {
    // Launch with compile-time embedded configuration
    cmd.Run(custom)
}

You can also invoke specific file operations directly from your code. For example, to compress files programmatically using Superfile's internal utilities:

package main

import (
    "github.com/yorukot/superfile/src/internal/file_operations_compress"
)

func main() {
    // Create a zip archive from selected files
    file_operations_compress.Zip([]string{"README.md", "LICENSE"}, "archive.zip")
}

This function is defined in src/internal/file_operations_compress.go and can be imported independently for batch processing scripts that leverage Superfile's file handling logic.

Summary

• Superfile provides a terminal-based, dual-pane file organization interface built on the Bubble Tea framework and written in Go.
• Install via single-line bash or PowerShell scripts, then launch with the spf command.
• Navigate using vim keys (h, j, k, l) and perform operations (r, c, m, d, a) defined in src/internal/handle_file_operations.go.
• Customize keybindings through TOML configuration files processed by src/internal/config_function.go.
• Integrate programmatically by importing packages from src/internal/ or embedding custom configurations at compile time.

Frequently Asked Questions

Is Superfile compatible with Windows?

Yes. While Superfile follows Unix-terminal conventions, it provides a PowerShell installation script and supports Windows file paths and trash operations. The src/internal/handle_file_operations.go implementation includes OS-specific handling for file deletion and path resolution, ensuring consistent behavior across macOS, Linux, and Windows environments.

How do I change the default keybindings in Superfile?

Create a custom hotkey file (e.g., customHotkeys.toml) in your Superfile configuration directory (usually ~/.config/superfile/) and reference it in your main config. The src/internal/config_function.go module loads these files at startup, merging your definitions with the embedded defaults found in src/superfile_config/vimHotkeys.toml.

Can I use Superfile to manage remote files or network drives?

Superfile operates on the local filesystem through standard Go file I/O operations. While it does not natively implement SFTP or NFS protocols, you can mount remote filesystems using your operating system's tools (sshfs, rclone mount, etc.), then navigate and organize those mounts within Superfile's dual-pane interface just like local directories.

What makes Superfile different from other terminal file managers like Ranger or Midnight Commander?

Superfile differentiates itself through its Bubble Tea-based architecture (providing smooth, reactive UI updates), embedded configuration system allowing compile-time customization, and modular plugin architecture using JSON IPC. Unlike Ranger (Python-based) or traditional Midnight Commander, Superfile offers a modern Go codebase with first-class support for embedding into other applications and extensive theming capabilities defined in TOML files.

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