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

> Learn to run shell commands in Superfile using the SPF prompt. Discover how to execute native commands with ':' and built-in SPF commands with '>'

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

---

**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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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:

```text
: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`](https://github.com/yorukot/superfile/blob/main/consts.go))

### Switching Back to SPF Mode

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

```text
>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`](https://github.com/yorukot/superfile/blob/main/tokenize.go) and matched against `defaultCommandSlice()`

### Changing Directories

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

```text
: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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/consts.go) for configuration and [`model.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/prompt/model.go) and [`utils.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/tokenize.go) file handles parsing and argument validation for these commands when entered with the `>` prefix.