← XeFM crftwr/xefm on GitHub · craftware

XeFM User Guide

Table of Contents

Getting Started

XeFM (Xenolith File Manager) is a powerful dual-pane file manager that runs both as a native desktop app (Windows, macOS) and in the terminal (Windows, macOS, Linux). It provides efficient file management with cloud storage integration, advanced search capabilities, and extensive customization options.

What Makes XeFM Special

Installation

Desktop app (Windows, macOS). Install from the Microsoft Store on Windows, or download the -macos.dmg from the latest release on macOS — Python is bundled in. This is the recommended way to run XeFM on the desktop; see the Desktop Mode Guide.

Terminal app (Windows, macOS, Linux). From PyPI:

pipx install xefm     # or:  uv tool install xefm,  or:  pip install xefm
xefm

pipx and uv keep XeFM in its own environment while putting the xefm command on your PATH — the right shape for an application. Or run uvx xefm to try it once without installing anything. Python 3.10 or later is all you need; every dependency, including the platform-specific ones, comes with it.

The two installs coexist and share ~/.xefm/; installing both is a perfectly normal setup. The README covers working from a source checkout.

Upgrading and uninstalling

Use the tool you installed with, so pick the row you started from:

Installed with Upgrade Uninstall
pipx install xefm pipx upgrade xefm pipx uninstall xefm
uv tool install xefm uv tool upgrade xefm uv tool uninstall xefm
pip install xefm pip install --upgrade xefm pip uninstall xefm

These are not interchangeable: each tool only knows about what it installed itself. uv tool upgrade xefm on a pipx- or pip-installed copy fails with `xefm` is not installed, and uvx xefm installs nothing at all, so there is never anything for it to upgrade.

The desktop packages upgrade through their own channel: the Microsoft Store updates automatically, and on macOS you install the new DMG over the old app.

Installation troubleshooting

First run: arrow keys navigate, Tab switches panes, ? opens help, Q quits.

Desktop Mode (Windows, macOS)

XeFM can run as a native desktop application with GPU acceleration, providing a modern windowed experience while maintaining the same keyboard-driven interface.

Quick Start

Install the desktop package (see Installation) and open XeFM from Launchpad / Spotlight on macOS, or the Start menu on Windows.

Running xefm --backend gui from a terminal opens the same window, but that is the development path — it gives the wrong app icon and, on macOS, attributes file permissions to your terminal rather than to XeFM. See Why not xefm --backend gui?.

Features

Desktop mode provides several advantages over terminal mode:

Configuration

Desktop-mode font settings live in ~/.xefm/config.py (they are ignored in terminal mode):

# GUI fonts and size — the grid is derived from the monospace face
MONO_FONT_NAME = 'Menlo'   # monospaced face for aligned columns (None = bundled default)
UI_FONT_NAME  = None       # proportional face for names/labels (None = bundled/OS default)
FONT_SIZE     = 12         # point size applied to both faces (8–72)

The window’s size and position are remembered automatically across runs (via the native macOS window autosave) — there are no window-geometry config keys.

Available Fonts

Common monospace fonts on macOS:

Backend Selection

The backend is chosen only by the --backend flag; there is no configuration-file preference. The default is terminal mode:

On Linux there is no desktop backend; use terminal mode.

Keyboard Shortcuts

All keyboard shortcuts work identically in both terminal and desktop modes. The same key bindings apply regardless of which backend you’re using.

For a complete list of all keyboard shortcuts, see the Keyboard Shortcuts Reference section. You can also press ? at any time while using XeFM to see the built-in help dialog with all available shortcuts.

Performance

Desktop mode provides excellent performance:

Troubleshooting Desktop Mode

Desktop mode doesn’t start:

Window doesn’t appear:

Font issues:

Performance issues:

Basic Usage

First Launch

When you first run XeFM, you’ll see:

Essential Keys

Core Features

Dual Pane System

See detailed documentation: Status Bar Feature

Display and Visualization

See detailed documentation:

File Operations

Basic Operations

Space    - Select/deselect file
C        - Copy selected files to the other pane
M        - Move selected files (or create a directory when nothing is selected)
K        - Delete selected files (also the Delete key)
R        - Rename file (or batch-rename multiple)
E        - Edit the selected files (or the focused file) with the external editor
Shift-E  - Create a new file

See detailed documentation:

Multi-Selection

  1. Use Space to select individual files
  2. Use A to select/deselect all files
  3. Use Shift-A to select/deselect all items (files + directories)
  4. Use Ctrl-Down / Ctrl-Up to jump the cursor to the next / previous selected item
  5. Perform operations on selected files

See detailed documentation: Key Bindings Feature

Advanced Operations

See detailed documentation: Batch Rename Feature

Safety Features

See detailed documentation: File Operations Feature

Directory Navigation

↑↓       - Move up/down in file list
←→       - Switch panes or enter/exit directories
Enter    - Enter directory or view file
Backspace - Go to parent directory
Home/End - Go to first/last file
Page Up/Down - Navigate by page

Quick Navigation

J        - Show favorite directories
Shift-J  - Jump to directory dialog
H        - Show directory history
O        - Sync current pane to the other pane
Shift-O  - Sync other pane to the current pane

See detailed documentation:

Search and Filtering

Search Methods

F        - Incremental search (filter as you type)
Shift-F  - Threaded filename search dialog
Shift-G  - Content search (grep) dialog
;        - Filter by pattern (*.py, test_*, etc.)
:        - Clear current filter

Sorting

S        - Open the sort dialog (key + order)
1        - Quick sort by name
2        - Quick sort by extension
3        - Quick sort by size
4        - Quick sort by date

See Sort Dialog Feature for the dialog’s controls (F/E/S/T choose a key directly; Left/Right choose ascending/descending).

Search Tips

See detailed documentation: Search Animation Feature

Text Viewing and Editing

Built-in Text Viewer

V        - View text file in built-in viewer
Enter    - Open item (views a text file)

Text Viewer Controls

q/ESC    - Exit viewer
↑↓       - Scroll up/down
←→       - Scroll left/right
Page Up/Down - Page scrolling
Home/End - Jump to start/end
n        - Toggle line numbers
w        - Toggle line wrapping
s        - Toggle syntax highlighting
/        - Search within file

External Editor

E        - Edit the selected files (or the focused file)
Shift-E  - Create a new file

With several files selected, E opens them all — files sharing an editor are passed to it in one launch (vim a.txt b.txt).

Configure your preferred editor in ~/.xefm/config.py:

TEXT_EDITOR = 'vim'  # or 'nano', 'code', etc.

See detailed documentation: Text Editor Feature

AWS S3 Integration

XeFM provides native AWS S3 integration for seamless cloud storage management. For comprehensive S3 documentation including setup, usage, troubleshooting, and advanced features, see the AWS S3 Support Feature Guide.

Quick Start

  1. Configure AWS credentials — aws configure, the AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION environment variables, or an IAM role (nothing to set up on EC2)
  2. Navigate to S3 buckets using s3:// URIs

S3 Navigation

# Navigate to S3 bucket
s3://my-bucket/

# Navigate to specific path
s3://my-bucket/path/to/files/

S3 Operations

S3 Examples

# Copy local files to S3
# 1. Select files in left pane (local directory)
# 2. Navigate right pane to s3://bucket/path
# 3. Press 'c' to copy

# View S3 text file
# 1. Navigate to s3://bucket/file.txt
# 2. Press 'v' to view (editing needs a local copy)

Advanced Features

Sub-shell Mode

Press Shift+X to enter sub-shell mode (terminal mode only — the desktop app has no terminal to hand over) with environment variables:

External Programs

Press x to show external programs menu. Programs have access to XeFM environment variables.

See detailed documentation: External Programs Feature

Pane Layout

[        - Make left pane smaller
]        - Make left pane larger
-        - Reset pane split to 50/50
{        - Make log pane larger (Shift+[)
}        - Make log pane smaller (Shift+])
_        - Reset log pane height (Shift+-)

File Comparison

=        - View diff between two selected text files (requires 2 files selected)
Shift-=  - Compare the two panes' current directories recursively
W        - Show file and directory comparison options

See detailed documentation: Diff Viewer Feature (file and directory diff)

View and Display Options

Z        - Show view options menu
Shift-Z  - Show settings and configuration menu
.        - Toggle visibility of hidden files

Color themes are switched from the menu bar (View → Theme); assign a key to toggle_color_scheme in ~/.xefm/config.py to cycle them from the keyboard.

Progress Animation

XeFM shows animated progress indicators during long-running operations like searching files.

See detailed documentation: Search Animation Feature

Customization

Configuration File

XeFM creates ~/.xefm/config.py on first run. Access it via:

For comprehensive configuration documentation, see the Configuration Feature Guide which covers all available options, examples, and best practices.

Key Bindings

XeFM supports powerful key binding customization with modifier keys and multiple keys per action:

KEY_BINDINGS = {
    # An action can have several keys — add your own alongside the defaults
    'quit': ['Q'],
    'help': ['?'],

    # e.g. add vim-style movement next to the arrow keys
    'cursor_up': ['UP', 'k'],
    'cursor_down': ['DOWN', 'j'],

    # Modifier key combinations
    'page_up': ['PAGE_UP', 'Shift-UP'],
    'page_down': ['PAGE_DOWN', 'Shift-DOWN'],

    # Extended form with a selection requirement
    'delete_files': {
        'keys': ['K', 'DELETE'],
        'selection': 'required'  # only when files are selected
    },
    'create_directory': {
        'keys': ['M'],
        'selection': 'none'      # only when nothing is selected
    },
}

Key features:

See detailed documentation: Key Bindings Feature

Themes

XeFM ships with several built-in themes (Dark+, Light+, Monokai, Dracula, Nord, Solarized, Gruvbox Dark, Solarized Light) and remembers the last one you used. Cycle themes at runtime with the T key, or pick one from View → Theme. Define your own with the THEMES dict in config.

See detailed documentation: Color Schemes Feature

Favorite Directories

FAVORITE_DIRECTORIES = [
    {'name': 'Projects', 'path': '~/dev'},
    {'name': 'Documents', 'path': '~/Documents'},
    {'name': 'S3 Bucket', 'path': 's3://my-bucket/'},
]

See detailed documentation: Navigation Dialogs Feature

External Programs

PROGRAMS = [
    {'name': 'Git Status', 'command': ['git', 'status']},
    {'name': 'Open in VSCode', 'command': ['code', '.']},
    {'name': 'View with less', 'command': ['less'],
     'options': {'terminal': True}},
]

See detailed documentation: External Programs Feature

Command Line Options

These apply to the terminal install and to source checkouts. The desktop packages take no command-line arguments — their launcher starts the native backend directly.

Basic Usage

python3 -m xefm                    # Terminal (curses) mode — the default
python3 -m xefm --left ~/projects  # Set the left pane's startup directory
python3 -m xefm --right ~/docs     # Set the right pane's startup directory

Backend Selection

--backend chooses the rendering backend:

python3 -m xefm --backend tui      # Terminal / curses (alias: --backend curses) — default
python3 -m xefm --backend gui      # Native window (aliases: --backend macos / windows)

--backend gui is the development path for desktop mode; for everyday use install the desktop package instead (why).

All Options

--backend {tui,curses,gui,macos,windows}  # Rendering backend (default: tui)
--left DIR                        # Left pane startup directory
--right DIR                       # Right pane startup directory
--version                         # Show version and exit
--help                            # Show help and exit

Combined Options

# Desktop window with custom startup directories (from a checkout)
python3 -m xefm --backend gui --left ~/projects --right ~/docs

Startup directories set with --left/--right override any saved pane history for that session; an invalid path falls back to the saved (or home) directory.

Troubleshooting

Common Issues

Desktop mode not starting (Windows / macOS)

Desktop mode on non-macOS systems

Desktop mode only works on macOS. On other platforms, XeFM automatically falls back to terminal mode.

Colors not working

Check your terminal’s color support and TERM environment variable

Wide characters display incorrectly

Check terminal Unicode support and locale settings

See detailed documentation: Wide Character Support Feature

Keys not responding

Check terminal key mappings and ESCDELAY setting

S3 access denied

Verify AWS credentials and bucket permissions

File operations failing

Check file permissions and disk space

Performance issues

Getting Help

See detailed documentation: Help Dialog Feature

Feature Documentation

For detailed information about specific features, see these dedicated guides:

File Operations

Remote and Cloud Storage

Viewers

Interface and Display

Configuration and Customization

Integration and Extensions

Keyboard Shortcuts Reference

XeFM provides extensive keyboard shortcuts for efficient file management. All shortcuts work identically in both terminal and desktop modes. Press ? at any time to see the help dialog with all available shortcuts.

Key Action
↑ / ↓ Move cursor up / down
← / → Switch to the left / right pane
Tab Switch the active pane
Enter Open item (enter directory, open file, or enter archive)
Backspace Go to the parent directory
Page Up / Page Down Scroll by a page
Cmd+Enter Open with the OS default application
Alt+Enter Reveal in the OS file manager

Selection

Key Action
Space Toggle selection and move down
Shift+Space Toggle selection and move up
Home Select all items
End Unselect all
A Toggle all files
Shift+A Toggle all items (files + directories)
Ctrl+↓ / Ctrl+↑ Jump the cursor to the next / previous selected item
W Compare-and-select against the other pane

File Operations

Key Action Selection
C Copy selection to the other pane required
M Move selection to the other pane required
M Create a new directory only when nothing is selected
K or Delete Delete selection required
R Rename the focused file/directory any
Shift+E Create a new file any
E Edit the selected file(s) (external editor) any
V View the file (built-in viewer) any
I Show file details any
= Diff two selected files 2 files
Shift+= Diff two directories recursively 2 dirs
Cmd+Shift+C Copy name(s) to the clipboard any
Cmd+Shift+P Copy path(s) to the clipboard any

Search, Filter and Sort

Key Action
F Incremental search (isearch)
Shift+F Filename search dialog
Shift+G Content (grep) search dialog
; Filter the pane by pattern
: Clear the filter
S Sort dialog (key + order)
1 / 2 / 3 / 4 Quick sort by name / extension / size / date

Archive Operations

Key Action Selection
P Create an archive from the selection required
U Extract the focused/selected archive any

Panes and Log

Key Action
[ / ] Make the left pane smaller / larger
- Reset the pane split
{ / } Make the log pane larger / smaller
_ Reset the log-pane height
Shift+↑ / Shift+↓ Scroll the log up / down
Shift+← / Shift+→ Page the log up / down
O Sync the current pane’s directory to the other pane
Shift+O Sync the other pane’s directory to the current pane

Places and Dialogs

Key Action
J Favorite directories
Shift+J Jump to a path
H History for the current pane
D Drives / storage selection dialog

Other

Key Action
? Show the help dialog
Q Quit XeFM
. Toggle hidden files
X External programs menu
Shift+X Enter subshell (command line) mode
Z View options menu
Shift+Z Settings / configuration menu
Ctrl+L Redraw the screen (always available; recovers the display after a terminal-multiplexer switch)
F5 Redraw the screen (rebindable via redraw in config)

Letter keys are case-sensitive. Most file-operation bindings use the uppercase letter (e.g. C, M, K, R), and their variants use Shift (e.g. Shift-F, Shift-E). All bindings are customizable — see below.

Customizing Key Bindings

All key bindings can be customized in your configuration file (~/.xefm/config.py). The enhanced key binding system supports:

Examples:

KEY_BINDINGS = {
    'page_up': ['PAGE_UP', 'Shift-UP'],  # Two ways to page up
    'cursor_up': ['UP', 'k'],            # add a vim-style alternative
    'delete_files': {
        'keys': ['K', 'DELETE'],
        'selection': 'required'          # Only when files selected
    },
}

See the Configuration section and Key Bindings Feature for complete documentation.

Tips and Tricks

Efficiency Tips

  1. Use Tab frequently: Quick pane switching is key to efficiency
  2. Learn multi-selection: Select multiple files with Space, then operate
  3. Use incremental search: Press ‘f’ and start typing to filter files
  4. Customize key bindings: Adapt XeFM to your workflow
  5. Use favorites: Set up bookmarks for frequently accessed directories

Workflow Examples

File Organization

  1. Navigate to source directory in left pane
  2. Navigate to destination in right pane
  3. Select files with Space
  4. Press ‘c’ to copy or ‘m’ to move

Development Workflow

  1. Set up favorites for project directories
  2. Use external programs for git operations
  3. Edit files with ‘e’ key
  4. Use content search to find code

S3 Data Management

  1. Navigate to local directory in left pane
  2. Navigate to s3://bucket/path in right pane
  3. Copy files between local and cloud storage
  4. Edit S3 configuration files directly

This comprehensive user guide covers all aspects of using XeFM effectively. For technical implementation details, see the developer documentation in the doc/dev/ directory.