How to Use the SPF Prompt for Running Shell Commands in Superfile

Use the : prefix in the superfile prompt to execute native shell commands, while the > prefix triggers built-in SPF commands like open, cd, or split.

The superfile terminal file manager by yorukot ships with a versatile dual-mode prompt system called the SPF prompt. This article explains how to leverage the SPF prompt for running shell commands directly from the file manager interface, with technical details drawn from the actual source code implementation.

Understanding the Dual-Mode Prompt Architecture

Superfile's interactive prompt operates through two distinct modes that share the same UI component (the prompt modal). The mode is toggled automatically by the first character you type at the start of the line.

SPF Mode vs Shell Mode

Mode	Prompt Character	Purpose
SPF mode	>	Runs built-in superfile commands such as open, split, and cd
Shell mode	:	Executes any native shell command on your host system

Where the Behavior is Defined

According to the yorukot/superfile source code, the prompt logic is centralized in src/internal/ui/prompt/consts.go:

• Prompt characters are declared at lines 15-17, establishing > and : as the mode-switching triggers
• Built-in command definitions reside in the defaultCommandSlice() function at lines 62-79, which enumerates supported SPF commands and their usage strings
• Mode detection occurs through modeString and shellPrompt helpers at lines 48-60, which examine the first character and set an internal shellMode flag
• Execution timeout for shell commands is controlled by shellSubTimeout at lines 28-30, defaulting to 1 second

The core prompt model in src/internal/ui/prompt/model.go receives key presses from Bubble Tea, checks the current mode when you press Enter, and routes the input accordingly.

Running Shell Commands with the SPF Prompt

When you enter shell mode by typing :, the raw line (minus the leading colon) is passed to exec.Command via a helper in model.go. The command runs in a subprocess with a configurable timeout, and superfile captures both stdout and stderr.

Basic Shell Execution

To run a simple shell command:

:ls -la

• The leading : activates Shell mode
• ls -la executes in your default system shell
• Output appears in the prompt area with a Success or Error prefix (defined by successMessagePrefix and failureMessagePrefix in consts.go)

Switching Back to SPF Mode

To execute superfile-specific actions, use the > prefix:

>open /path/to/project

• The > character returns to SPF mode
• The built-in open command creates a new panel at the supplied path
• The text is tokenized via tokenizePromptCommand in tokenize.go and matched against defaultCommandSlice()

Changing Directories

>cd src/internal/ui/prompt

• cd changes the current panel's working directory
• No leading colon means superfile processes this through the SPF command dispatcher rather than your system shell

Advanced Usage and Configuration

Combining Commands in Workflows

The prompt supports switching modes mid-session, enabling script-like workflows:

:git status
>cd src/internal/ui/prompt
:go test ./...

This sequence runs a repository status check via shell, moves the panel using an SPF command, then executes tests through the shell again.

Shell Command Timeouts

By default, shell commands timeout after 1 second as defined by shellSubTimeout in src/internal/ui/prompt/consts.go. If a command exceeds this limit, the subprocess is killed and an error message is displayed. You can modify this behavior by adjusting the timeout constant in the source before building.

Built-in SPF Command Reference

The defaultCommandSlice() function in consts.go defines the available SPF commands that work with the > prefix. These include directory navigation (cd), panel management (open, split), and other file-manager-specific actions. Each command is validated for proper argument counts through the tokenizer logic in tokenize.go.

Summary

• Use : to enter Shell mode and execute any system command (ls, git, go, etc.)
• Use > to enter SPF mode and run superfile built-in commands like open, cd, or split
• Source files driving this behavior are located in src/internal/ui/prompt/, particularly consts.go for configuration and model.go for execution logic
• Timeout protection defaults to 1 second (shellSubTimeout) to prevent hanging the UI
• Output handling automatically prefixes results with Success or Error indicators based on exit codes

Frequently Asked Questions

What is the difference between SPF mode and Shell mode in superfile?

SPF mode (triggered with >) runs superfile-specific internal commands defined in defaultCommandSlice() such as open, cd, and split. Shell mode (triggered with :) passes commands directly to your system shell via exec.Command, allowing you to run any native binary or script available in your PATH.

How do I change the shell command timeout in superfile?

The timeout is hardcoded as shellSubTimeout in src/internal/ui/prompt/consts.go at lines 28-30, defaulting to 1 second. To change it, modify this constant in the source code and rebuild superfile. There is currently no runtime configuration option for this value.

Can I run interactive shell commands through the superfile prompt?

No. The current implementation in src/internal/ui/prompt/model.go and utils.go executes commands through exec.Command with captured stdout/stderr, which does not support interactive TTY sessions. Commands requiring user input during execution will timeout or fail after shellSubTimeout (1 second).

Where are the built-in SPF commands defined?

Built-in commands are defined in the defaultCommandSlice() function within src/internal/ui/prompt/consts.go (lines 62-79). This function returns a slice of command structures containing usage strings and metadata. The tokenize.go file handles parsing and argument validation for these commands when entered with the > prefix.

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