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

> Master terminal file management with Superfile. This guide explains how to use Superfile for efficient organization via its dual-pane interface and vim-style shortcuts for copy, move, rename, and delete operations.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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
bash -c "$(curl -sLo- https://superfile.dev/install.sh)"

```

Windows users can run the PowerShell alternative:

```powershell
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`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go), which parses command-line flags, loads the embedded configuration from [`main.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/main.go) embeds default configurations using `//go:embed` directives and delegates execution to the command runner.

The core components include:

- **[`src/cmd/main.go`](https://github.com/yorukot/superfile/blob/main/src/cmd/main.go)**: Parses CLI flags and constructs the top-level Bubble Tea program, injecting the embedded filesystem configuration.
- **[`src/internal/model.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/sidebar/sidebar.go)**: Renders the dual-panel layout and processes panel-specific input events.
- **[`src/internal/handle_file_operations.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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:

```go
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:

```go
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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/internal/handle_file_operations.go).
- Customize keybindings through TOML configuration files processed by [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/customHotkeys.toml)) in your Superfile configuration directory (usually `~/.config/superfile/`) and reference it in your main config. The [`src/internal/config_function.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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.