Metadata-Version: 2.4
Name: commandertui
Version: 1.7.2
Summary: Dual-pane retro terminal file manager: compare, sync, copy and move folders
Author: Humberto Barchini
License-Expression: MIT
Project-URL: Homepage, https://github.com/juniorbarchini-oss/commandertui
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.0
Requires-Dist: send2trash>=1.8
Requires-Dist: textual-image>=0.14.4
Requires-Dist: pillow>=10.3
Requires-Dist: pypdf>=5.0
Requires-Dist: python-docx>=1.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pypdfium2>=4.30
Provides-Extra: images
Requires-Dist: textual-image>=0.14.4; extra == "images"
Requires-Dist: pillow>=10.3; extra == "images"
Provides-Extra: documents
Requires-Dist: pypdf>=5.0; extra == "documents"
Requires-Dist: python-docx>=1.1; extra == "documents"
Requires-Dist: openpyxl>=3.1; extra == "documents"
Provides-Extra: pdf-render
Requires-Dist: pypdf>=5.0; extra == "pdf-render"
Requires-Dist: pypdfium2>=4.30; extra == "pdf-render"
Requires-Dist: textual-image>=0.14.4; extra == "pdf-render"
Requires-Dist: pillow>=10.3; extra == "pdf-render"
Provides-Extra: all
Requires-Dist: textual-image>=0.14.4; extra == "all"
Requires-Dist: pillow>=10.3; extra == "all"
Requires-Dist: pypdf>=5.0; extra == "all"
Requires-Dist: python-docx>=1.1; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: pypdfium2>=4.30; extra == "all"
Dynamic: license-file

# 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:

```bash
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](https://pypi.org/project/commandertui/) (Python 3.11+). Recommended via `pipx`:

```bash
pipx install commandertui
```

Or inside an activated virtual environment:

```bash
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:

```bash
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](https://sw.kovidgoyal.net/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:

```bash
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):

```bash
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:

```ini
# hyprland.conf
windowrulev2 = float, class:^(commandertui)$
windowrulev2 = size 1174 637, class:^(commandertui)$
windowrulev2 = center, class:^(commandertui)$
```

```lua
-- 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

```bash
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](https://www.anthropic.com/claude) (Anthropic) through
[Claude Code](https://claude.com/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](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.
