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.7.2 — on-demand file previews on Linux and macOS, with preview fixes. 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 resolves the repository dependencies. Image rendering and visual PDF pages use optional AUR packages; the app and its updater do not require them. PDF text preview works without the PDF renderer. Install image rendering separately if desired:

yay -S --needed python-textual-image
git clone https://github.com/juniorbarchini-oss/commandertui.git
cd commandertui/packaging/arch
updpkgsums
makepkg -si

python-pypdfium2 is also optional; its current AUR dependency on libpdfium.so-64 does not match the AUR libpdfium package's provided soname, so visual PDF pages may be unavailable until that package dependency is corrected.

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

The standard installation and normal pip/pipx updates include all preview engines: images, PDF text and visual pages, Word .docx, and Excel .xlsx. The extras remain accepted aliases; PyPI users do not need an additional install step:

pipx install "commandertui[images]"      # inline terminal image rendering (textual-image + Pillow)
pipx install "commandertui[documents]"   # PDF text + pagination, DOCX, XLSX (pypdf, python-docx, openpyxl)
pipx install "commandertui[pdf-render]"  # PDF text + optional visual page rendering (pypdf, pypdfium2 + images)
pipx install "commandertui[all]"         # everything above
# or with pip inside a venv: pip install commandertui

CSV/TSV parsing uses Python's standard library. Reduced distro installations still show metadata when a preview engine is unavailable.

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 On-demand file preview (Esc returns to the same file): text (w wrap), Markdown (m source), images (f mode), PDF ([/] pages, g visual), DOCX text/tables, XLSX/CSV/TSV tables ([/] or s sheets), and metadata for unsupported/legacy files; on macOS o runs Quick Look (or "preview_mode": "quicklook" in ~/.config/commandertui/settings.json)
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, sort order, preview mode)
├── preview.py                # safe on-demand preview loader, isolated worker + macOS Quick Look
├── preview_docs.py           # Stage 2 adapters (PDF, DOCX, XLSX, CSV/TSV) + OOXML safety checks
├── preview_screen.py         # full-screen file previewer (text, Markdown, images, PDF, tables)
├── 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 deduplication engine, no desktop GUI wrapper — those are different problems. (Automatic live preview while navigating and legacy binary/OpenDocument conversion via LibreOffice are intentionally out of scope.)

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.

File preview (Stage 1 + Stage 2)

Pressing v opens an on-demand full-screen preview for the file under the cursor (Esc closes the viewer and returns to the same file and cursor row):

  • On-demand only: Navigating through folders (including rclone FUSE mounts) never reads or downloads file contents until v is pressed.
  • Process isolation & cancellation: Previews (including ZIP/OOXML validation, parsing, and PDF rasterization) run inside an isolated worker process group with an outer wall-clock grace margin (+2s above the internal 5s/10s read/decode deadline) so pressing Esc, switching pages/sheets rapidly, or hitting blocked I/O terminates cleanly and discards stale results.
  • Text & code: Read-only viewer with line numbers (w toggles soft wrap). Byte (512 KiB), line (10,000 lines), and internal time (5s) caps apply; terminal escape/control sequences are sanitized, and previewed files are never executed.
  • Markdown: Rendered view with external link opening disabled (m toggles rendered vs. raw read-only source). Files with more than about 300 blocks (paragraphs, list items, table rows) open as source text, because rendering them would freeze the viewer.
  • Images: Included textual-image + Pillow engines render via Kitty TGP / Sixel / half-cell / Unicode (f cycles auto / halfcell / unicode), enforcing byte (25 MiB), pixel (25 MP), and internal decode time (10s) limits. If an engine is unavailable, CommanderTUI shows metadata and header dimensions.
  • Image mode and terminal compatibility: Without a saved preference, Herdr sessions start in halfcell; other terminals start in auto. Pressing f saves the chosen mode in ~/.config/commandertui/settings.json for subsequent previews and restarts, including when switching terminals. If an image or visual PDF page appears blank, press f to try another mode. Images fit the viewport with a maximum of 256 terminal cells per axis; deferred Rich image-rendering errors fall back to half-cell rendering.
  • PDF: Uses the included pypdf engine for selectable text per page ([ / ] to move pages, 200k char cap/page, 25 MiB file cap, 10s limit). Pressing g switches to visual page rendering with pypdfium2 (rasterized in the isolated worker, capped at 25 MP / 1600 px, forms non-interactive). Encrypted or corrupt PDFs fall back to safe metadata.
  • Word .docx: Uses the included python-docx engine to extract headings, paragraphs, and tables in readable document order (not pixel-exact Word layout), guarded by pre-parse ZIP/OOXML limits (25 MiB compressed, 50 MiB total uncompressed, 2,000 entries, XML DOCTYPE/ENTITY rejection, 512 KiB text cap, 200 tables cap). Encrypted/corrupt files fall back to metadata.
  • Spreadsheets (.csv / .tsv / .xlsx): Displayed as an interactive table capped at 500 rows, 50 columns, 20,000 cells, and 200 chars/cell. .csv files detect their delimiter (, ; tab or |). A sheet or PDF page that fails to load leaves the previous one on screen with a notice, so navigation is never lost. For .xlsx, [ / ] steps worksheets and s opens the sheet selector; the included openpyxl engine reads in read_only=True, data_only=True, keep_vba=False, keep_links=False mode, showing stored cached values (or literal formula strings as data if no cached value exists) without ever running macros, evaluating formulas, or fetching external links.
  • Legacy Office, OpenDocument, media & archives: Legacy .doc, .xls, .ppt, macro-enabled .docm/.xlsm/.pptm, OpenDocument (.ods/.odt/.odp), audio/video, archives, binaries, FIFOs, and broken symlinks show safe metadata and why integrated preview is disabled (LibreOffice / external converters are never invoked).
  • macOS Quick Look: Available inside the viewer via o (Quick Look), or set "preview_mode": "quicklook" in ~/.config/commandertui/settings.json to make v launch qlmanage -p directly.

Metadata

Release files for commandertui 1.7.2

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.7.2
File Size Uploaded Provenance Actions
commandertui-1.7.2.tar.gz 180.1 kB With provenance Details for commandertui-1.7.2.tar.gz

Built distribution (wheel)

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

Total release size: 303.9 kB

Release files / commandertui-1.7.2.tar.gz

Download URL commandertui-1.7.2.tar.gz
Size 180.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7a745446b584f4ded276a749f54f7e72400eb7a1a55a77afa51b4af5b3ff964d
BLAKE2b-256 checksum
How to use checksums
a0a3634b8ff02fcd5bfcfb93005119013390b701e60206b274e0664ad9810924
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 15, 2026.

Transparency log

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

Download URL commandertui-1.7.2-py3-none-any.whl
Size 123.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
05944f8884f0ac2f3bfe052bd20245dca6b29f9e38a9a9f81234f10438c48941
BLAKE2b-256 checksum
How to use checksums
4125e1d8ea23302d5b4e2aeea4201272da3745e3fb9040a7cfffce90035b83e6
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 15, 2026.

Transparency log

Security for commandertui 1.7.2

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.7.2.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 15, 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