📁 tfm

A fast, keyboard-driven terminal file manager built with React and Ink.

tfm is a lightweight terminal file manager designed for users who prefer navigating the filesystem without leaving the keyboard. It provides familiar Vim-style navigation, clipboard operations, filtering, customizable keybindings, and an extensible configuration system.

---

✨ Features

• ⚡ Fast terminal-based interface
• ⌨️ Fully keyboard-driven workflow
• 📂 Directory navigation
• 📋 Copy, cut, and paste files/directories
• 🗑️ Safe deletion with confirmation
• 🔍 Interactive file filtering
• 📁 Create and rename directories
• 🎨 Configurable keybindings and theme
• 👀 Toggle hidden files
• 📊 Multiple sorting modes
• 🆘 Built-in help overlay

---

Requirements

Before installing, ensure you have:

• Node.js 18 or newer
• pnpm (recommended)

---

Installation

Clone the repository:

git clone https://github.com/knowaraj/tfm.git
cd tfm

Install dependencies:

pnpm install

Build the project:

pnpm build

Make the CLI available globally:

npm link

or (depending on your pnpm version):

pnpm link --global .

Note: npm link is generally the most reliable option because pnpm --global behavior varies across versions.

---

Development

During development you don't need to rebuild or relink manually.

Start watch mode:

pnpm dev

The project automatically rebuilds whenever source files change.

---

Keyboard Shortcuts

Key	Action
↑ / k	Move up
↓ / j	Move down
Enter / l	Open selected directory
← / h	Go to parent directory
Space	Select / deselect item
y	Copy selected items
x	Cut selected items
p	Paste
D	Delete (confirmation required)
/	Search / filter entries
:	Open command mode
?	Toggle help
.	Show / hide hidden files
s	Cycle sorting (Name → Size → Modified Time)
q	Quit

---

Commands

Open the command bar by pressing:

:

Available commands:

Command	Description
mkdir <name>	Create a new directory
rename <new-name>	Rename the highlighted file or directory
cd <path>	Change the current working directory

Examples:

:mkdir projects

:rename notes.txt

:cd ~/Downloads

---

Configuration

tfm can be customized through a configuration file.

Create:

~/.config/tfm/config.json

Example configuration:

{
  "keymap": {
    "up": "k",
    "down": "j",
    "enter": "l",
    "back": "h",
    "select": " ",
    "yank": "y",
    "cut": "x",
    "paste": "p",
    "delete": "D",
    "search": "/",
    "command": ":",
    "help": "?",
    "quit": "q"
  },
  "theme": {
    "cursorColor": "white",
    "accentColor": "yellow",
    "errorColor": "red"
  },
  "showHidden": false,
  "sortMode": "name"
}

Configuration Notes

Partial Configuration

All configuration fields are optional.

You only need to specify the values you want to customize.

For example:

{
  "theme": {
    "accentColor": "cyan"
  }
}

Only the accent color changes—everything else continues using the default settings.

Keymap

Custom keybindings override the defaults.

Any keys that are omitted continue using the built-in mappings.

Theme

Customize the interface colors:

• cursorColor
• accentColor
• errorColor

Other Options

Option	Default	Description
showHidden	false	Show hidden files by default
sortMode	name	Default sorting mode (name, size, mtime)

Invalid Configuration

If the configuration file contains invalid values, tfm falls back to the built-in defaults and displays a warning instead of failing to start.

---

Built With

• React
• Ink
• TypeScript
• Node.js

---

License

MIT

---

Contributing

Contributions, bug reports, and feature requests are welcome!

If you'd like to contribute:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

---

Author

Built with ❤️ using React and Ink.