[← README](../../README.md) · [Docs index](../README.md) · [Reference](README.md) # The terminal app `coxswain` (or `cox` for short) is Coxswain in a terminal: two Norton Commander panels that work in any terminal and over SSH. It shares its core with the desktop app, reads the same `config.toml` and uses the same search helper, so an index built by one serves the other. This page says what it has, what it lacks and why, and where it behaves differently. ![The terminal app: two blue panels, the git repository rocket on the left with its branch line, the home folder on the right](../screenshots/tui-panels.png) *The terminal app in the NC theme. The left panel is a git repository: the bottom line shows `master`, ahead by one, and a count per kind of change.* ## Contents - [How to use it](#how-to-use-it) - [What it has](#what-it-has) - [What only the desktop app has](#what-only-the-desktop-app-has) - [Where the two differ](#where-the-two-differ) - [Archives in the terminal app](#archives-in-the-terminal-app) - [Git history in the terminal app](#git-history-in-the-terminal-app) - [Search by meaning in the terminal app](#search-by-meaning-in-the-terminal-app) - [What you see](#what-you-see) - [Settings and config.toml](#settings-and-configtoml) - [The terminal it needs](#the-terminal-it-needs) - [Questions](#questions) ## How to use it 1. Start it from a shell: ```sh coxswain # both panels in the current folder coxswain ~/src ~/Downloads # left and right coxswain notes.md # its folder, with the cursor on the file ``` 2. Move with the arrows, **Enter** to open, **Tab** for the other panel, **F5** to copy, **F10** to quit. The keys are the same as in the desktop app: see [Every default key](../panels/keys.md). 3. **F9** lists every action the terminal app has, with its key. **F1** shows the keys. **F12** opens Settings. Every flag: [Command-line flags](command-line-flags.md#the-terminal-app-coxswain). ## What it has | Feature | Page | |---|---| | The [first-run guide](../panels/first-run.md) on the very first start, full screen in the panel colours; **F1** then **G** shows it again | [The first-run guide](../panels/first-run.md) | | Two panels, NC's keys, marking, groups, sorting, quick search, hidden files, go to folder, swap, other panel here | [Panels and keys](../panels/README.md) | | The command line (with `cd`) and the user menu (**F2**) with the scripts folder's scripts | [The command line](../commands/command-line.md), [The user menu](../commands/user-menu.md), [Scripts](../commands/scripts.md) | | View (**F3**) and edit (**F4**) in your own programs | [View and edit](../commands/view-and-edit.md) | | A viewer for CycloneDX cryptography BOMs (**F3** on one): the rated tree, a half-block sunburst, filters and compare | [Cryptography bills of materials](../previews/bom.md) | | Chess games (**F3** or **Alt+K** on a PGN, EPD or FEN file or a Polyglot book), full screen: the games as a table with a filter, a game on a board with its moves (pieces drawn from block characters), or the book's moves | [Chess games](../previews/chess.md) · [Game pieces in the terminal](../previews/game-pieces.md) | | Go games (**F3** or **Alt+K** on an SGF file), full screen: the games as a list, a game on a board of Unicode stones with its captures, variations and comments | [Go games](../previews/go.md) | | Draughts games (**F3** or **Alt+K** on a PDN file), full screen: the chess table of games, a game on a numbered board of coloured squares with ● men and ♚ kings, its captures and variations | [Draughts games](../previews/draughts.md) | | Xiangqi games (**F3** or **Alt+K** on a PGN file whose tags say `Game "Chinese Chess"`, or a DhtmlXQ game), full screen: the chess table of games, a game on a board of box lines with the river and the pieces as red and black characters | [Xiangqi games](../previews/xiangqi.md) | | Shogi games (**F3** or **Alt+K** on a KIF or CSA file), full screen: the chess table of games, a game on a board of kanji with Gote's pieces marked v, the pieces in hand, variations and comments | [Shogi games](../previews/shogi.md) | | Bridge deals (**F3** or **Alt+K** on a PBN file), full screen: the table of deals with pairs, contract and result, a deal as four hands round the table with its auction, trick by trick | [Bridge deals](../previews/bridge.md) | | A viewer for build provenance (**F3** on one): inputs → build → outputs, the outputs checked against the files here, compare | [Build provenance](../previews/provenance.md) | | Copy (**F5**), move and rename (**F6**), new folder (**F7**), delete to the trash (**F8**) or for good (**Shift+F8**) | [Files](../files/README.md) | | Archives as folders: look inside, copy and move in and out, take out, extract (**Ctrl+E**), pack (**Alt+F5**), passwords | [Archives in the terminal app](#archives-in-the-terminal-app) | | Find (**Alt+F7**, **Ctrl+F**; **Shift+F7** for *In files*, **Ctrl+F7** for Ask): names, words in files, meaning and history in groups, the scope chip, the Ask row (**Alt+Enter**) and the answer in place | [Find](../search/find-file.md) | | Search by meaning, turned on in Settings → Finding files or with `coxswain --meaning on` | [Search by meaning in the terminal app](#search-by-meaning-in-the-terminal-app) | | Folder sizes in the Size column, and on `..` the size of the folder above once known | [Folder sizes](../panels/folder-sizes.md) | | Space (**Alt+U**), full screen: a treemap in flat coloured cells, the bytes by type and the largest files beside it | [Space](../panels/space.md#in-the-terminal-app) | | The git line, a glyph per file, and the last commit of the entry under the cursor in the info line; on `..` the upstream (ahead, behind), the last fetch and the remote, and on a repository's folder its own | [Git in the panels](../panels/git.md), [Upstream, remote and last fetch](../panels/git.md#upstream-remote-and-last-fetch) | | Open in your git tool (**Alt+G**): lazygit, gitui or tig in place of the panels, or your desktop client, to commit, push or pull | [Open in your git tool](../panels/git.md#open-in-your-git-tool) | | The git config as git uses it (**Alt+C**), full screen: each value with its scope and file, secrets hidden until **Enter** | [Git config](../panels/git-config.md#in-the-terminal-app) | | Git history as folders (**Ctrl+G**): the commits of a file or folder, the files as they were, **F3** and **F5** on them | [Git history in the terminal app](#git-history-in-the-terminal-app) | | Git branches (**Alt+B**) and worktrees (**Alt+W**): a branch's files, switching (**Alt+S**), new branches | [Git branches and worktrees](../panels/git-branches.md#in-the-terminal-app) | | ZFS snapshots as folders (**Alt+Z**), the diff of a file against now (**Enter**), copied back with **F5**; the dataset in the panel's bottom border | [ZFS snapshots as folders](../files/zfs-snapshots.md#in-the-terminal-app) | | Properties (**Alt+Enter**) as text, with ZFS, the FreeBSD package and file flags; *F9 → File flags* and *F9 → Files of this package* | [Properties](../files/properties.md#in-the-terminal-app) | | Your cloud accounts under **Alt+F1** / **Alt+F2**, as NC's drive menu | [Clouds](../organise/clouds.md#in-the-terminal-app) | | FreeBSD's boot environments and jails under **Alt+F1** / **Alt+F2**, as NC's drive menu | [FreeBSD](../systems/freebsd.md#boot-environments-and-jails) | | Every theme's colours, Nerd Font or ASCII glyphs, your own themes | [Themes](../customise/themes.md), [Glyphs and fonts](../customise/glyphs-and-fonts.md) | | All 31 languages (`coxswain --languages` lists them) | [Languages](../customise/languages.md) | | Your own keys from `[keys]` | [Changing keys](../customise/keys.md) | | The command list (**F9**) and help (**F1**) | [The command list](../panels/command-list.md) | | Settings (**F12**, *12 Settings* on the F-key bar; also **Shift+F10** or **F9** → *Settings*, `coxswain --settings`): the desktop app's areas and options, full screen, saved at once; the install line of a missing program, copied with **Space** | [Settings in the terminal app](../customise/settings.md#in-the-terminal-app) | | The mouse: click, double-click, right-click marks, wheel | [The mouse](../panels/mouse.md) | | Update checks and notices, in the status line; the version in the terminal's title | [Update checks](updates.md), [Notices](../panels/notices.md) | ## What only the desktop app has | Feature | Why the terminal app lacks it | |---|---| | [The preview pane](../previews/README.md) | A terminal cannot draw PDFs, pictures, pages or diagrams. **F3** shows the file in the built-in viewer instead | | [Tabs, back and forward](../panels/tabs-and-panes.md), one pane or two | NC's two fixed panels are the terminal app's layout; **Ctrl+O** is taken by the command output | | [Columns and thumbnails views](../panels/views.md), the columns menu | Miller columns and thumbnails need more room and pictures than a terminal has | | [The sidebar](../organise/sidebar.md), [favourites](../organise/favourites.md), [colour tags](../organise/tags.md), [folder notes](../organise/notes.md) | They need a side pane and editing widgets the panels do not have room for. They are kept in `state.json`, which both apps share, so they are there when you open the desktop app | | [The clipboard](../files/clipboard.md) (**Ctrl+C**, **Ctrl+X**, **Ctrl+V**) and dragging files out ([Drag and drop](../files/drag-and-drop.md)) | A terminal has no file clipboard or drag source; **Ctrl+C** belongs to the terminal. Files dropped on the terminal are taken: *Copy here* or *Move here* ([In the terminal app](../files/drag-and-drop.md#in-the-terminal-app)) | | [Batch rename](../files/batch-rename.md) (**Ctrl+M**) | It needs a live preview table of old and new names | | [Finding duplicates](../files/duplicates.md) (**Ctrl+D**) | A long-running scan with groups to tick; use `coxswain-gui --duplicates FOLDER` | | [Restoring the last session](../panels/session.md) | It starts where you start it, as a shell command does | Their keys are bound in the terminal app too (both apps share one keymap). Pressed there, the status line says *Colour tag is available in the desktop app (coxswain-gui)*, with the action's name. The **F9** list and **F1** help leave them out. ## Where the two differ | | Terminal app | Desktop app | |---|---|---| | **F3** | Opens the file in the [built-in viewer](../commands/view-and-edit.md#the-built-in-viewer), highlighted, with search and go to line (`viewer` in the config runs another program) | The preview pane on or off | | **F4** | `editor`, `$VISUAL` or `$EDITOR`, in the terminal; else the [built-in editor](../commands/editor.md) | `editor` without a terminal, or the default application | | **Shift+F4** | The [built-in editor](../commands/editor.md), full screen | The built-in editor, in a window | | **Ctrl+O** | Shows the terminal with the last command's output, *Panels hidden · any key brings them back* under it; any key comes back ([The command line](../commands/command-line.md#the-output-flashed-by-in-the-terminal-app-where-is-it)) | One pane or two | | **Enter** on a program | Runs it in the panel's folder and waits for Enter | Hands it to the desktop | | **Enter** on another file | Opens it in its default application | Opens it in its default application | | A command's output | In the terminal, the panels hidden meanwhile | In the preview pane | | `wait` in `[[user_menu]]` | Waits for Enter afterwards (`-- press Enter --`) | Shows the output even when there is none | | Changes on disk | Read again after operations, commands, a change in a panel's folder and **Ctrl+R** (*Refresh*) | Folders on screen are read again by themselves | | Theme | `theme` (default `nc`), colours only; `look` is ignored | `[gui] theme` (default `cyber`), with its look | | Hidden files at start | Always from `show_hidden` | From the last session | | Properties (**Alt+Enter**) | The facts as text; your file flags with *F9 → File flags*, permissions with `chmod` | A dialog that also changes the permissions and your file flags | | Clouds, boot environments and jails | Under **Alt+F1** / **Alt+F2** | In the sidebar | | Marked size | Files only: `4.2 MB in 3 marked` | Measured folders count too | | Find, **F3** | Views the hit in the built-in viewer | Does nothing (**F4** edits in both) | | Inside an archive | The panel title ends in `[archive]` | A badge and a tint on the pane | | In a git history | The panel title ends in `[this branch's history · Alt+A: all branches]` or `[commit a1b2c3d]` | A badge (*history of main.rs*, *commit a1b2c3d*) and a tint | | The last commit | In the info line under the panel: `a1b2c3d 2026-09-30 14:02 Ada` | A *Last commit* column, and in the preview pane | | An archive's password | Asked in a *Locked archive* box, shown as stars | Asked in a dialog | | The F-key bar | Norton Commander's labels: *RenMov*, *Mkdir*, *PullDn* | *Move*, *New folder*, *Commands* | | Copying an install line | **Space** on the row in Settings: to the terminal's clipboard with OSC 52 | A **Copy** button | | Notices | Shown once in the status line, then counted as seen; the ones not shown yet are listed in *Settings → Overview*, where **Enter** opens the area that does it | Counted on **⚙ Settings** and listed under *Settings → Overview → What's new* until dismissed or acted on; a problem with search is also a button with `×` in the status line | | What a version brought | `coxswain --whats-new`, pointed to once after an upgrade, and *Settings → Overview* | *Settings → Overview → What's new* | | Update notice | `Coxswain X.Y.Z is available: brew upgrade coxswain` in the status line, checked at start and then every hour (GitHub asked once a day) | A button that opens the release page, checked the same way | | Window title | Sets the terminal's title: `Coxswain X.Y.Z` | The window's title | | Hebrew | Letters reversed in terminals without bidi support | Mirrored layout | ## Archives in the terminal app Zip, tar (plain, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst` and their short forms) and 7z archives open as folders, as in the desktop app ([Archives as folders](../files/archives.md)). | To | Do | |---|---| | Look inside | **Enter** on the archive. The panel's title becomes `/home/me/tools.zip [archive]` | | Copy a file out | **F5** with the other panel on a real folder | | Copy into the archive | **F5** from the other panel while this one is inside the archive: the files are added | | Move out, rename inside | **F6** | | Make a folder inside | **F7** | | Take something out | **F8**. It asks *Take … out of tools.zip? The archive is written anew without it; there is no trash inside an archive.* | | Extract a whole archive | **Ctrl+E**: a box titled *Extract "tools.zip"*, its field *To:* holding the other panel's folder; **Enter** makes a folder named after the archive there | | Pack into a new archive | **Alt+F5**: a box titled *Pack 3 items*, its field *To (Tab: .zip, .7z, .tar.gz, …):* proposed as `name.zip` (or the format used last) in the other panel; **Tab** / **Shift+Tab** swap the ending ([Formats](../files/pack-and-extract.md#formats)) | **Enter** on a file inside an archive does not open it; the status line says *tools.zip is an archive: F5 copies this file out of it*. **Passwords.** When an encrypted zip or 7z is opened, copied from or extracted, a box titled *Locked archive* asks *Its password (kept in memory while the app runs, never saved):*. The password is typed as stars. A wrong one asks again: *That password did not open it. Try again:*. **Esc** gives up. A password given to look inside is kept in memory until the app quits, so moving around in the archive does not ask again; one given for a copy or extract is used for that run only. See [Passwords for encrypted zip and 7z](../files/archive-passwords.md). RAR is not read, in either app: see [Archives as folders](../files/archives.md#questions). ## Git history in the terminal app The same as in the desktop app ([Git history as folders](../panels/git-history.md)): | To | Do | |---|---| | See a file's or folder's commits | **Ctrl+G** on it (on `..` for the folder you are in). The title becomes `…/main.rs/@history [this branch's history · Alt+A: all branches]`; each row is the graph in box-drawing characters (`●─╮`, `│ ●`, `├─╯`), the names of the branches whose tip it is in brackets, then `a1b2c3d subject`, its date in *Modified* | | See what is not pushed or not merged | **Alt+Y**: the title ends in `[against upstream · Alt+Y: this branch]` and the bottom border reads `Upstream: origin/main, 1 ahead, 2 behind · Last fetch: …`, each commit marked `↑` (not pushed) or `↓` (not merged) ([Against upstream](../panels/git-history.md#against-upstream)) | | See every branch's commits | **Alt+A** in the list: the title ends in `[every branch's history · Alt+A: this branch]`, and **Alt+A** again goes back ([The graph](../panels/git-history.md#the-graph)) | | See who made a commit | Put the cursor on it: the info line shows its id, date and author | | Browse the files as they were | **Enter** on a commit. The title ends in `[commit a1b2c3d]` | | Read an old file | **F3**: the built-in viewer shows a copy of it as it was | | Get an old file or folder back | **F5** to the other panel | | Go back | **Backspace**: to the commits, then to the folder on disk | **F4**, **F6**, **F7** and **F8** do nothing there: a history is read-only, and the status line says so. ## Search by meaning in the terminal app Search by meaning works the same in both apps: the search helper does it, and Find's *About this* group shows its hits. What differs is how you turn it on. 1. Run `coxswain --meaning on`. It downloads the built-in model (about 465 MB), showing *Downloading: 42 %*, sets `[search] meaning = true` and starts a new helper. Or `coxswain --meaning ollama` or `coxswain --meaning server URL MODEL` for a server ([Command-line flags](command-line-flags.md#--meaning)). 2. Start `coxswain` and press **Ctrl+F** for Find. 3. Type what you look for. Files found by meaning alone are under *ABOUT THIS*, with a second line, dim and in italics, holding the passage that was close. Files with your words are under *IN FILES*, those close in meaning first, the words marked in the theme's search-hit colour. While it is off, *ABOUT THIS* says *Find files about your words too, in any language, even without the words. · Enter: Set up · Del: not again*; **Enter** runs `coxswain --setup-search`. Find's footer says *meaning for 3,437* once the helper has it running. Full details: [Search by meaning](../search/meaning.md), [on a server](../search/servers.md). ## What you see - **The panels:** double blue frames, the folder path in the title (with `[archive]` inside an archive), columns Name, Size and Modified; `SUB-DIR` in the Size column until a folder is measured, and on `..` the size of the folder above once known, else `UP--DIR`. - **Changes on disk** show by themselves: a file another program writes, copies in or deletes appears or goes in the panel within a second, the cursor staying on its name, and the git line follows commits and checkouts (the panels' folders and their repository's `.git` are watched). A folder inside an archive or a history is read again when you go back to it. - **The status line** under the panels: the result of the last operation (`Copied 3 files`), a notice, an update, or the size of what is marked. - **The command line** with the panel's folder as the prompt, and the F-key bar below it: **F1** to **F10** as in NC, then *12 Settings* (**F12**). - **Dialogs** are grey boxes in the middle. The title says what and how many (*Copy 3 items*, *Move or rename "budget.txt"*), the field is labelled *To:*, and the bottom line is the same as in the desktop app: *Enter Copy · Esc Cancel*, with the dialog's own verb (*Move*, *Create*, *Pack*, *Extract*, *Unlock*, *Go*, *Mark*, *Move to bin* …). In a question **Y** and **N** work too. - **Errors** are titled with what failed (*Could not copy "budget.txt"*), then the cause in one line (*Permission denied*), then, when there is more, a *Details:* line and the raw text below it; *Enter Close* at the bottom. See [When something goes wrong](../files/copy.md#when-something-goes-wrong). ![The terminal app's Find at In files with "engine" typed: each hit a name and folder, the passage on the next line, engine highlighted](../screenshots/tui-text-search.png) *Find in the terminal app: a hit in a file takes two lines, the file and the passage.* ## Settings and config.toml **F12** (*12 Settings* on the F-key bar; **Ctrl+,** too, where the terminal passes it on, and **Shift+F10** or **F9** → *Settings*), or `coxswain --settings`, opens Settings full screen: the same areas and options as the desktop app's, read from the same description in `coxswain-core`, and written to the same `config.toml` at once, your comments kept. **←** **→** pick the area, **↑** **↓** the option, **Space** flips or chooses, **Enter** types a value or opens a list, **/** finds a setting, **Esc** closes. The whole walk-through: [Settings in the terminal app](../customise/settings.md#in-the-terminal-app). The keys only the terminal app reads are `theme`, `viewer`, `bom_viewer` and `provenance_viewer` (*Looks* and *Behaviour*). A change made by hand in `config.toml` needs the app started again. Things that do more than set a value also have flags, for scripts: | To | Run | |---|---| | Set up search by meaning and Ask, step by step | `coxswain --setup-search` | | Turn search by meaning on (downloads the model) | `coxswain --meaning on` | | Use Ollama on this machine, or another server | `coxswain --meaning ollama [MODEL]`, `coxswain --meaning server URL MODEL` | | Back to the built-in model | `coxswain --meaning builtin` | | Turn it off, or delete the model | `coxswain --meaning off`, `coxswain --meaning delete` | | Start the search helper with your session | `coxswain --index-service on` (`off` to stop) | | See every default | `coxswain --dump-config` | Each `--meaning` and `--index-service` flag, and each `[search]` change in Settings, starts a new helper with the new settings. ## The terminal it needs - **True colour** (24-bit) for the built-in themes, which use exact RGB. Nearly every current terminal has it. - **A Nerd Font** as the terminal's font for icons and git glyphs, or `glyphs = "ascii"`. - **Mouse reporting** for clicks and the wheel. While Coxswain has the mouse, most terminals select text with **Shift** held down. - **Right-to-left text** only for Hebrew: Konsole, or GNOME Terminal with bidi on. - **Keys sent as escape sequences** (F1 to F12, the arrows, Home, End), as every terminal sends them. A key pressed right after **Esc**, while the app was busy, can arrive in the same read as the Esc (macOS Terminal does this): the app puts it back together, so **Esc** then **F10** quits rather than typing `[21~`. ## Questions #### Do I have to press anything when another program changes a folder? No. The terminal app watches the folders in its two panels, not their subfolders, and their repository's `.git`: a change is read once it has settled (a quarter of a second without another, or every two seconds while a build writes on), and only the panel showing it is read again, the cursor on the same name. **Ctrl+R** still reads both panels again at once. The desktop app watches its panes' folders the same way. #### How do I change a setting without editing config.toml? Press **F12** (or click *12 Settings* on the F-key bar). Settings opens full screen at Overview; **→** goes to the next area. On a switch such as *Ask before deleting*, **Space** flips it and the bottom line says *Saved to …/config.toml*. `coxswain --settings=confirm_delete` opens with the cursor on it. #### Where did `Enter = OK Esc = Cancel` go? 2.0 gave both apps one key line, which names what **Enter** does: *Enter Copy · Esc Cancel*, *Enter Create · Esc Cancel*. The keys are the same; **Y** and **N** still answer a question. #### How do I copy an install line? There is no Copy button. In *Settings → Finding files* (**F12**), put the cursor on the missing program under *Programs that read more* and press **Space**. The terminal puts the line on its clipboard (OSC 52, over ssh too); the bottom says *Copied: …*. Your terminal must allow OSC 52; if it does not, type the line from the row. #### Can I use the terminal app over SSH? Yes. It runs on the remote machine, with that machine's files, `config.toml` and search helper. Only the terminal's keys and colours cross the connection. #### Why can't I select text with the mouse? Coxswain takes the mouse for clicks and the wheel. Hold **Shift** while selecting (in most terminals), or quit with **F10** first. #### How do I see a file's contents without leaving the panels? There is no preview pane in the terminal. **F3** shows it full screen in the [built-in viewer](../commands/view-and-edit.md#the-built-in-viewer), highlighted in the theme's colours; **Esc** comes back to the panels. #### I pressed Alt+T and it said "is available in the desktop app". Why is the key there at all? Both apps share one keymap, so your `[keys]` work the same in each. The terminal app knows the desktop-only actions and says so in the status line instead of doing nothing. **F9** and **F1** leave them out. #### How do I open a file inside a zip in the terminal app? To look at it: **Enter** on the zip to go inside, the cursor on the file, **F3**. A copy goes to your viewer (a games file opens in the games view); a locked file asks for its password first. To edit it or open it in another program, copy it out with **F5** first: **Enter** and **F4** on a file inside only say *tools.zip is an archive: F5 copies this file out of it*. #### It asks for an archive's password every time I start it. Passwords are never saved: they live in memory until the app quits. That is on purpose, so no password is ever written to disk. #### Does the terminal app remember where I was? No: it starts where you start it, with the folders you name. Tags, notes and favourites the desktop app set are kept in `state.json`, which the terminal app does not show. #### How do I turn on search by meaning without the desktop app? `coxswain --meaning on` (or `coxswain --setup-search`), then Find (**Ctrl+F**): files found by meaning are under *ABOUT THIS*. See [Search by meaning in the terminal app](#search-by-meaning-in-the-terminal-app). --- [← Previous: Reference](README.md) · [Next: Command-line flags →](command-line-flags.md)