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
.tmpfile next to the destination and are committed withos.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.rclonemounts from/proc/mounts(Linux) ormount(macOS) and resolves local mount paths back to their nativercloneremote spec (e.g./mnt/gdrive/docs->gdrive:docs). - Parallel multi-threading: Offloads file batches and recursive folder transfers to a single parallel
rcloneworker (--transfers 16 --checkers 16) with live JSON progress streaming directly to the UI progress bar. - Graceful cancellation: Pressing
Escterminates the transfer process group cleanly (start_new_session=True+killpg), leaving no orphaned background workers. - Safety fallback: If
rcloneis not installed or returns a configuration error (e.g. remote section not found inrclone.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 userrclone mountprocess 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.gzarchive 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_filteron 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.