Skip to main content

CommanderTUI

Dual-pane terminal file manager: compare two folders, sync them, or move files/folders between them (and to USB/SMB/any mounted path) — with a phosphor-green 80s-terminal look and a short modem-style boot animation.

Status: v1.4.0 — 153/153 tests passing. MIT licensed.


Why this exists

A safe, simple alternative to heavier dual-pane file managers. It was written after an earlier attempt of the same idea had to be scrapped for running an unauthenticated local HTTP server. This project deliberately:

  • Never opens a network port. Pure terminal UI (Textual), no HTTP server (the only outgoing request is the update check on startup, which you can turn off), no webview.
  • Local deletes use the desktop trash. Network/remote deletes require an explicit permanent-delete confirmation, defaulting to Cancel. Remote data never enters a trash backend or gets copied into the local trash.
  • Never overwrites in place. Copies stream into a hidden .tmp file next to the destination and are committed with os.replace — a crash or Ctrl+C never leaves a half-written file.
  • Never guesses on a conflict. Two-way sync copies each side's exclusive files automatically, but a file changed on both sides is always shown to you, never auto-resolved.

Install

Arch Linux / Omarchy. An AUR package is on the way (yay -S commandertui). Until then, build it from the PKGBUILD in this repo. makepkg pulls in everything it needs:

git clone https://github.com/juniorbarchini-oss/commandertui.git
cd commandertui/packaging/arch
makepkg -si

Remove it with sudo pacman -R commandertui.

PyPI (Linux / macOS / WSL). It is a standard package on PyPI (Python 3.11+). Recommended via pipx:

pipx install commandertui

Or inside an activated virtual environment:

pip install commandertui

macOS. Same Python package (pipx install commandertui), plus kitty for the standalone window. Places lists the volumes under /Volumes (system volumes such as Recovery and Preboot are hidden) and FUSE mounts inside your home folder. To get a double-clickable app with the CommanderTUI icon:

packaging/macos/build_app.sh            # builds packaging/macos/CommanderTUI.app
packaging/macos/build_app.sh --install  # also copies it to /Applications

The app opens kitty at 1174x637 px and runs commandertui. It looks for the command in ~/.local/bin (pipx), Homebrew, /usr/local/bin, your PATH, and a source checkout's .venv. Tested by the author on macOS with a Time Machine volume, Google Drive and OneDrive mounts.

From a source checkout (development):

python3 -m venv .venv && .venv/bin/pip install -e . -r requirements-dev.txt
bin/commandertui [left-dir] [right-dir]

Run

Command What it does
cmdrtui Opens it in its own terminal window. This is also what the CommanderTUI app-launcher entry runs
commandertui Runs it inside the terminal you are in
commandertui DIR1 DIR2 Opens with those two folders side by side

cmdrtui uses your desktop's default terminal (xdg-terminal-exec). If that isn't available it tries foot, alacritty, kitty and ghostty. The window always gets the app-id/class commandertui, so a window-manager rule can float it. It needs about 1174x637 px to fit every key hint. On Hyprland:

# hyprland.conf
windowrulev2 = float, class:^(commandertui)$
windowrulev2 = size 1174 637, class:^(commandertui)$
windowrulev2 = center, class:^(commandertui)$
-- Omarchy Lua config (~/.config/hypr/hyprland.lua)
o.window("^commandertui$", { float = true, center = true, size = { 1174, 637 } })

Keys

Key Action
Tab Switch active pane
↑/↓, Enter Navigate, open directory (or sort column when header is focused with ↑ beyond row 0)
Backspace Go to parent directory
Space Mark/unmark item under cursor
F2 Rename the item under the cursor (never overwrites an existing name)
F4 Edit the file under the cursor with $VISUAL / $EDITOR (falls back to nano, vim or vi); CommanderTUI pauses and comes back when you close the editor
F5 Copy marked (or item under cursor) to the other pane
F6 Move marked to the other pane
F7 Create a folder in the active pane
F8 / Delete Delete marked: local items to trash; network/remote items permanently after an explicit warning (Cancel by default)
z Create .tar.gz archive of marked items into the other pane
x Extract archive under cursor (.tar.gz, .tgz, .tar.bz2, .tar.xz, .tar, .zip) into the other pane
/ Filter the active pane by name (contains, ignores case) as you type; Enter keeps it, Esc clears it
+ / - / * Mark / unmark by pattern (*.iso, or plain text = contains) / invert marks, over the rows shown
u Check for updates now (also the Updates button): asks PyPI right away and offers the new version if there is one
v Quick Look file preview (macOS only): opens qlmanage -p for the file under cursor; press v again or close the window to dismiss
i Size: file/folder count and total bytes of marked items (background, Esc stops it)
h Show/hide hidden (dot) files in both panes
t Color theme: Phosphor green (default), Phosphor amber, Nord, Gruvbox, Dracula, Tokyo Night, Catppuccin Mocha, Solarized Dark, Monokai, Textual Dark. Previews as you move, Enter keeps it (saved in ~/.config/commandertui/settings.json), Esc goes back
p Places: jump to a mounted drive (USB/SMB/rclone), saved bookmark or saved network location. Inside: a add a network location, s save the active pane's folder as a bookmark, d delete a saved one, e unmount a mounted SMB share, l change the login of a saved network location (forgets the session, then anonymous or another user)
c Compare: full recursive diff between the two panes' current folders, with size and date of both sides (and which is newer when a file changed)
r Refresh both panes
q Quit

While a copy/move runs, the progress window shows two bars (current file and whole job, by bytes) plus speed in Mb/s and time left. Esc asks to cancel: finished files stay, the file in progress is discarded (never left half-written), and a move never removes a source it didn't fully copy.

Places lists only what is mounted right now: USB drives (/run/media, /media, /mnt — checked with ismount, so an empty on-demand mount point doesn't show), GVFS/Nautilus network shares, FUSE mounts inside $HOME (e.g. rclone mount), and saved bookmarks.

Network locations (Linux, needs gio/GVFS; macOS supports SMB via smbutil/osascript and /Volumes): in Places press a, pick SMB, SFTP or FTP and type the server's IP or name. For SMB the app lists the shares on the server and you pick one; SFTP/FTP connect straight in (Linux only). The location is saved in ~/.config/commandertui/network.json (protocol, host, share and user only -- never a password) and reappears in Places, mounting itself when picked. If the server asks for a login, gio asks for it in the terminal and can remember it in the system keyring, exactly like Nautilus (on macOS, the system login dialog asks and saves it in Keychain). For SMB and FTP the app first asks Anonymous (no login) or User and password; anonymous connects with gio mount --anonymous, with no user, workgroup or password prompt, and is remembered per location. Choosing User and password forgets any earlier session for that server first, so the login prompt always appears.

If the GVFS backend (or gvfs-fuse, which gives a mounted share a folder to browse) for the chosen protocol is not installed (a bare Ubuntu server, for example, has none), the app says so and offers to install it for you (apt-get install gvfs-backends gvfs-fuse, pacman -S gvfs gvfs-smb or dnf install gvfs-smb gvfs-fuse); it asks for your sudo password in the terminal and only runs if you answer Install now.

Every key also has a clickable box on the bottom bar: one row on wide windows (168+ columns), two rows when narrower (120 columns is the practical minimum). The active pane has the thick border and the inverted path bar; each path bar shows the free space of that disk, and the marked count and total size.

Updates

On every launch, in the background while the start-up animation plays (its CHECKING UPDATES line shows the result), the app asks PyPI for the latest version (a plain GET, nothing about you is sent). If a newer one exists you get a dialog -- Update now / Later / Skip this version -- and the header keeps saying update X available (press u). It never installs on its own. Update now hands the terminal over and runs the command that matches how it was installed:

Installed as Update runs
Arch package (makepkg) rebuilds from the release's PKGBUILD with makepkg -si --nocheck (tests already ran in the release workflow) (your sudo password is typed in the terminal, never read by the app)
pipx pipx upgrade commandertui
pip pip install --upgrade commandertui
git checkout no button: the dialog tells you to git pull

Turn the check off with commandertui --no-update-check or by setting COMMANDERTUI_NO_UPDATE_CHECK=1. COMMANDERTUI_FAKE_LATEST=9.9.9 shows the dialog without a real release, to see how it looks. The logic lives in one self-contained file, commandertui/updater.py, written to be copied into other apps.

Inside Compare:

Key Action
m Mirror: make right identical to left
u Update: copy new/changed left → right, never deletes
b Two-way: propagate each side's exclusive changes; conflicts (changed on both sides) are listed, never guessed
Space Mark a row for manual handling
c Copy marked rows in whichever direction they diverge
Esc Back to the panes

Every bulk or destructive action shows a plain-language summary (count of operations, total bytes) and requires y to confirm.

Architecture

commandertui/
├── models.py          # FileEntry, DiffEntry, OperationQueue, QueuedOp
├── scanner.py          # os.scandir recursive tree walk
├── diff.py             # pure comparison: left-only / right-only / modified / identical
├── plan.py              # diff -> OperationQueue (mirror / update / two-way)
├── sync.py               # atomic copy/move (streamed, tmp+replace), checksum verify
├── trash.py               # 3-layer safe delete (send2trash / gio trash / manual)
├── rclone_bridge.py        # Turbo Copy: parallel rclone engine for FUSE mounts
├── archive.py              # create .tar.gz and safe extract (.tar.*, .zip)
├── executor.py             # runs an OperationQueue against the filesystem
├── bookmarks.py             # detected mounts (USB/SMB/rclone) + saved places
├── netlocations.py           # SMB/SFTP/FTP locations via gio (list shares, mount, save)
├── theme.py                  # phosphor green/amber themes + the stylesheet (Textual theme variables)
├── settings.py               # saved settings (color theme)
├── boot.py                    # startup "modem" reveal animation
├── widgets.py                  # FilePanel: one pane's directory listing
├── modals.py                    # Confirm / Places / Input / Size / Message screens
├── progress_screen.py            # two-bar transfer progress + cancel
├── run_queue.py                   # confirm -> run queue in a worker thread
├── compare_screen.py              # full diff view + bulk/manual sync actions
├── app.py                          # CommanderApp: wires panes + keybindings
└── cli.py                           # argument parsing, entrypoint

Tests

pip install -r requirements-dev.txt
pytest
black commandertui tests   # formatter, line length set in pyproject.toml

Engine (scanner/diff/plan/sync/executor) is fully unit tested against a real filesystem (tmp_path). The UI has smoke tests via Textual's Pilot (boot sequence dismisses, pane switching, mark→copy→confirm end to end).

Not in scope

No file preview, no deduplication engine, no desktop GUI wrapper — those are different problems.

Credits

Designed and tested by Humberto Barchini. The code was written together with Claude (Anthropic) through Claude Code: Claude Sonnet 5 built the first version, Claude Opus 5.5 did most of v0.2 and the v1.0 packaging.

License

MIT — see LICENSE.

Copy/move conflicts

F5 (Copy) and F6 (Move) check the destination before transferring. Existing items open a dialog focused on Skip: overwrite, skip, rename, or ask for each conflict (with Apply to all remaining). Copy also offers Only newer and Merge for existing folders; Merge asks how to handle conflicting files. Overwrite on folders keeps destination-only files. Repeated source names use the same policy; rename selects free _1, _2, … names.

Transfers run with cancellable progress. Skipped and unfinished sources stay marked. Moves verify each copied file before trashing its source; skipped and failed files stay in the source. Existing files always require a decision, even when size and date match: Overwrite copies/moves them, while Skip (or Only newer for identical files) retains them. The completion message reports copied, skipped, failed, and identical files retained by a move.

Turbo Copy (rclone mounts)

When transferring files to or from cloud storage mounted via rclone mount (fuse.rclone, such as Google Drive or OneDrive), traditional sequential POSIX file I/O over FUSE incurs one HTTP round-trip per file, making transfers of thousands of small files very slow.

CommanderTUI includes an automatic Turbo Copy engine:

  • Automatic detection: Detects active fuse.rclone mounts from /proc/mounts (Linux) or mount (macOS) and resolves local mount paths back to their native rclone remote spec (e.g. /mnt/gdrive/docs -> gdrive:docs).
  • Parallel multi-threading: Offloads file batches and recursive folder transfers to a single parallel rclone worker (--transfers 16 --checkers 16) with live JSON progress streaming directly to the UI progress bar.
  • Graceful cancellation: Pressing Esc terminates the transfer process group cleanly (start_new_session=True + killpg), leaving no orphaned background workers.
  • Safety fallback: If rclone is not installed or returns a configuration error (e.g. remote section not found in rclone.conf), CommanderTUI automatically falls back to its standard atomic copy/move engine. Local folders containing symlinks also route through the standard engine to preserve symlinks properly.
  • Trash safety: Moving files from local storage to an rclone mount copies to the remote first and only sends the local source to the desktop trash after successful transfer confirmation.
  • Selective cache invalidation: On completion, cache flush signals (SIGHUP) are sent strictly to the specific user rclone mount process managing the affected mountpoint, never interfering with other active rclone tasks (such as backups or syncs).

Failed or cancelled rclone batch moves

Local originals go to the trash only after rclone confirms their upload, or after the entire batch exits successfully. A failed batch keeps every unconfirmed source, even when rclone emits no per-file errors. Cancelling keeps all local originals. Reports count only confirmed, completed moves; a source that could not be sent to the trash is reported as a failure.

Archives (tar / zip)

CommanderTUI supports creating and extracting archives directly between panes:

  • z (Create .tar.gz): Compresses marked items (or the item under the cursor) into a .tar.gz archive created in the opposite pane. If the destination is on an rclone mount, the archive is assembled in a local temporary file first and then transferred cleanly to the cloud.
  • x (Extract archive): Extracts the archive under the cursor (.tar.gz, .tgz, .tar.bz2, .tar.xz, .tar, or .zip) into the opposite pane.
  • Safe extraction: Before extracting, CommanderTUI inspects the archive contents for existing files at the destination. If conflicts exist, a choice dialog asks whether to Replace (old ones to trash), Skip existing, or Cancel.
  • Security: Built-in protection against directory traversal attacks (ZipSlip / Tar traversal) preventing files from extracting outside the destination folder, complemented by Python's data_filter on Python ≥ 3.12.

Local trash and network deletion

An item is local only when its most specific mount is a known local disk filesystem (including fuseblk, tmpfs and the root overlay), or a Linux block-device mount. Unknown filesystems are treated as remote. This includes SMB/CIFS, GVFS, rclone/Google Drive, SFTP/sshfs, NFS and WebDAV. A server's own ext4 disk remains local; viewing its SMB share from another machine is remote.

F8 and Compare & Sync warn before permanently deleting remote items and default to Cancel. Mixed batches keep local items on the trash path. Replacing remote destinations, archive extraction with Replace and archive overwrite also warn that replacement is permanent. MOVE removes a remote source directly after its copy is verified (rclone handles its own remote moves). Directory symlinks are unlinked without deleting their targets.

The local trash fallback uses a same-filesystem rename only. An EXDEV error fails safely instead of downloading or copying data across filesystems. Cancelling stops subsequent operations; completed permanent deletions cannot be undone. A completed or failed worker always closes its progress screen.

Delete confirmations show GVFS connection URIs (for example smb://server/share) or the mount path and filesystem type. The extra note about local items going to trash appears only for mixed selections. File sizes come from metadata; folder or unreadable sizes stay unknown and suppress the total instead of showing zero or scanning a remote tree before confirmation.

Metadata

Release files for commandertui 1.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for commandertui 1.6.0
File Size Uploaded Provenance Actions
commandertui-1.6.0.tar.gz 130.6 kB With provenance Details for commandertui-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for commandertui 1.6.0
File Interpreter ABI Platform Actions
commandertui-1.6.0-py3-none-any.whl Python 3 none any Details for commandertui-1.6.0-py3-none-any.whl

Total release size: 223.3 kB

Release files / commandertui-1.6.0.tar.gz

Download URL commandertui-1.6.0.tar.gz
Size 130.6 kB
Tags Source
SHA-256 checksum
How to use checksums
fe3be86ac73f2d8c8e7a7d83ce29d56f3bcd797f9cc15f1dc5321c9231cbc004
BLAKE2b-256 checksum
How to use checksums
d1e997a27f69331709a0e043160f5143fad0e5f5ff4fadc0b206259ca901a922
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / commandertui-1.6.0-py3-none-any.whl

Download URL commandertui-1.6.0-py3-none-any.whl
Size 92.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eb7db5d5140b1219b705bd1b1f38611b5738e20030f9a1d93714ea6b6bcbe7be
BLAKE2b-256 checksum
How to use checksums
db7c2e7946a98417998be84cb9f19b190eaa8e7714707b68b2b10ad1aeb14ef7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for commandertui 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for commandertui-1.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page