[← README](../README.md)

# Coxswain documentation

Every feature of both apps, the terminal app (`coxswain`) and the desktop app (`coxswain-gui`), has its own page: what it does, how to use it with the exact keys in both apps, what you see on screen, its settings and `config.toml` keys, how the terminal app differs, and the questions people ask. Each area has an index of its own. Pages end with *Previous* and *Next* links in the order below, so the docs can be read from start to end.

New here? Start with [The first-run guide](panels/first-run.md), [The screen](panels/the-screen.md) and [Every default key](panels/keys.md). Coming from 1.x? Read [What's new in 2.0](whats-new-2.md). Puzzled? See [Questions, collected](faq.md). Every version: [the changelog](changelog.md).

## The map

```mermaid
mindmap
  root((Coxswain))
    Panels and keys
      The screen and notices
      Moving, marking, sorting
      Tabs, views, folder sizes
      Git, history, branches
      F1, F9, Shift+F10
    Organise
      Colour tags
      Folder notes
      Favourites and sidebar
    Commands
      Command line
      User menu F2 and scripts
      View F3, edit F4
      Built-in editor Shift+F4
    Search
      Find: names, text, meaning
      Ask your files
      The search helper
      Built-in models
    Previews
      Text, code, documents
      Office, data, media
      CBOMs and provenance
      LaTeX, tools, containers
    Files
      Copy, move, delete, undo
      Archives as folders
      Properties, duplicates
      Compare files Shift+F2
      Compare folders Ctrl+F2
      ZFS snapshots
    Customising
      Settings
      Themes and looks
      Languages, keys, glyphs
    Reference
      Terminal app, flags
      config.toml, privacy
      Where things are kept
    Systems
      FreeBSD, other BSDs, illumos
      Linux, Android, ChromeOS
      macOS, Windows
```

## [Panels and keys](panels/README.md)

| Page | What it covers |
|---|---|
| [Panels and keys](panels/README.md) | The area's pages, finding what Coxswain can do (F1, F9, Shift+F10, hints), and the main keys of both apps |
| [The first-run guide](panels/first-run.md) | The four steps shown on the first start (panels and keys, how far Find looks, looks with the Nerd Font check, privacy), skipping, opening it again (F1, Settings → Overview) |
| [The screen](panels/the-screen.md) | Panels, active panel, title bar with the version, status line and notices, F-key bar (*12 Settings* at its right end in the terminal app), archives shown in the pane, starting in a folder |
| [Notices and what's new](panels/notices.md) | The version in the title, the tips, the count on Settings, *What's new* and `coxswain --whats-new` |
| [Moving around and going to a folder](panels/moving.md) | Cursor keys, Enter, parent, other panel, refresh, Alt+F1/Alt+F2, Ctrl+L, cd |
| [Quick search](panels/quick-search.md) | Alt+letter to jump to a name |
| [Marking files](panels/marking.md) | Insert, + - *, patterns, marking with the mouse, what uses the marks |
| [Sorting and hidden files](panels/sorting.md) | Ctrl+F3 to Ctrl+F6, headers, the rules, Alt+. and show_hidden |
| [Tabs, back and forward, one pane or two](panels/tabs-and-panes.md) | Tabs, back and forward, one pane or two (Ctrl+O; in the terminal app the last output, with *Panels hidden · any key brings them back*), the splitter |
| [Views: details, columns, thumbnails](panels/views.md) | Details, Miller columns, thumbnails, the columns menu, the age chip |
| [Folder sizes](panels/folder-sizes.md) | Where they come from, how fresh, the size on `..` once known, measuring again, switching off |
| [Space: where the space goes](panels/space.md) | Alt+U, a treemap of a folder or a drive: every file a rectangle by its size, coloured by kind, the bytes by type, the largest files, zoom, Delete from there; both apps |
| [Git in the panels](panels/git.md) | The git line (worktree, detached HEAD, merge or rebase under way), upstream, remote and last fetch (the git line's tooltip, the terminal app's info line on `..`, a repository folder's own on hover), file glyphs, the last commit per file, the diff, recent repositories, Open in your git tool (Alt+G), the git config (Alt+C), user menu commands |
| [Git history as folders](panels/git-history.md) | Ctrl+G, the commits of a file or folder with their graph, Alt+A all branches, Alt+Y against upstream, the files at a commit, preview and diff, F3, F5, read-only, limits |
| [Git branches and worktrees](panels/git-branches.md) | Alt+B, the branches, a branch's files, switching (Alt+S) and new branches, Alt+W, the worktrees, limits |
| [Git config](panels/git-config.md) | Alt+C, the config as git uses it: each value with its scope and file, values set earlier dimmed, secrets hidden until shown, F4 opens a line's file, copying a line, read-only |
| [Jujutsu in the panels](panels/jujutsu.md) | A Jujutsu repository through jj: the change id, nearest bookmark and changed files on the line, its history (Ctrl+G) and bookmarks (Alt+B) as folders, read-only; git where Settings prefers it |
| [Mercurial in the panels](panels/mercurial.md) | A Mercurial repository through hg: the bookmark or branch and changed files on the line, its history (Ctrl+G), bookmarks and branches (Alt+B), switching with hg update --check (Alt+S) and new bookmarks; the repository's own hgrc never read |
| [Subversion working copies](panels/subversion.md) | A Subversion working copy's status from .svn/wc.db alone: revision, branch and changed files, no server asked; the history from the server once you say yes to it; Alt+G opens a terminal for update and commit |
| [CVS working copies](panels/cvs.md) | A CVS working copy's status from CVS/Entries alone: branch or tag and changed files, no server asked; the history from the server once you say yes to it; Alt+G opens a terminal for update and commit |
| [The mouse](panels/mouse.md) | Clicks, marks, drags, path bar, tabs, splitters, in both apps |
| [The command list (F9) and Help (F1)](panels/command-list.md) | The command list (F9) and Help (F1) |
| [Features and questions (F1)](panels/features.md) | Help's second tab: every feature by area with its keys and two or three questions answered, the filter (diacritics ignored), Show me (its page on GitHub, only when pressed), F1 in a dialog, the terminal app's Tab and Enter |
| [What can I do with this? The action menu and hints](panels/action-menu.md) | Shift+F10 / Menu / ⋯: the actions that fit what is under the cursor, with their keys; Find, Ask and the panels in it; hints on the status line and in Find, three times each; right-click: mark or menu; --hints reset |
| [What the apps remember](panels/session.md) | The desktop session, state.json, what is forgotten |
| [Every default key](panels/keys.md) | Every default key of both apps, keys that are not actions, keys inside dialogs |

## [Tags, notes, favourites and the sidebar](organise/README.md)

| Page | What it covers |
|---|---|
| [Tags, notes, favourites and the sidebar](organise/README.md) | The area, and its keys in both apps |
| [Colour tags](organise/tags.md) | Alt+T, seven colours, the dot after the name, tags belong to a path |
| [Folder notes](organise/notes.md) | Alt+N, the notes field in the preview pane, saved on leaving it, the footer icon |
| [Favourites](organise/favourites.md) | Named groups in the sidebar, add with +, remove with ×, rename and delete groups |
| [The sidebar](organise/sidebar.md) | Ctrl+B, places, drives with free space, clouds, favourites, twelve recent git repositories |
| [Clouds](organise/clouds.md) | One entry per cloud account found on the machine (OneDrive, Google Drive, Dropbox, Nextcloud, iCloud, rclone and gvfs mounts), sidebar and Alt+F1, per system, no logins |

## [Commands, the user menu and scripts](commands/README.md)

| Page | What it covers |
|---|---|
| [Commands, the user menu and scripts](commands/README.md) | The area, and its keys in both apps |
| [The command line and its output](commands/command-line.md) | The command line: typing, cd, Ctrl+Enter, the shell, output in the terminal (Ctrl+O, with *Panels hidden · any key brings them back*) and in the preview pane |
| [The user menu, F2](commands/user-menu.md) | The user menu (F2): the built-in entries per system (terminal, SHA-256, git status), Add your own command, [[user_menu]], %f %d %s %%, wait, when, entries to copy |
| [Scripts](commands/scripts.md) | The scripts folder, run from F2 in both apps with the marked files as arguments |
| [View and edit, F3 and F4](commands/view-and-edit.md) | View and edit (F3, F4): viewer, editor, $PAGER, $VISUAL, $EDITOR, the preview pane in the desktop app |
| [The built-in editor, Shift+F4](commands/editor.md) | Editing inside Coxswain in both apps: keys, find and replace, undo, go to line, saving with the file's encoding, line endings and permissions, a file changed on the disk meanwhile |
| [Opening files](commands/opening-files.md) | Enter and double-click on folders, archives, programs and files, default applications |

## [Search](search/README.md)

| Page | What it covers |
|---|---|
| [Search](search/README.md) | The groups of Find, all pages, keys at a glance |
| [Smart search in a few minutes](search/setup.md) | The guided setup (Settings → Set up…, `coxswain --setup-search`): parts, hardware table, Ollama, Lemonade, LM Studio, llama.cpp, the GPU check, start with my session |
| [Find](search/find-file.md) | One field for names, words, meaning and Ask: the groups and their order, the kinds (Tab) and prefixes, the scope (Ctrl+F inside Find), the Ask row and the answer in place, every key and state |
| [Names everywhere](search/names.md) | The name index, how it stays current and fast, the scope chip for this folder, exclude/roots/watch |
| [Name syntax](search/name-syntax.md) | Everything's words, !, |, wildcards, ext:, file:, folder:, case:, paths, quotes |
| [Text in files](search/text.md) | The *In files* group: how words match (every word, then any of them), the passages, the scope, what is read and when, search.db |
| [Documents it reads](search/documents.md) | PDF, Word, RTF, spreadsheets, slides, mail, books, notebooks, diagrams, Markdown |
| [Scans, pictures and older Office files](search/scans.md) | Tesseract, pdftoppm, LibreOffice and how to install them |
| [Other formats with Apache Tika](search/tika.md) | OneNote, XPS, CHM, Outlook .pst, MHTML, Hangul and Access files read by Apache Tika in a container (opt-in, no network); what it costs, what is read again |
| [Transcripts of speech](search/transcripts.md) | Whisper on request: a file or a folder (hours and time asked first), background, pausable, never on battery; the model by hardware from Hugging Face, whisper.cpp installed or its container |
| [Diagrams read as sentences](search/diagrams.md) | Draw.io, Mermaid, Graphviz, PlantUML, with examples and limits |
| [Git history in search](search/history.md) | Commit messages, authors and changed paths of your repositories, found by text and meaning, opened at the commit |
| [Inside archives](search/archives.md) | Files in zip, 7z and tar found by name, text, meaning and Ask; which archives, changes, locked ones, limits |
| [Choosing the folders: folders read, names only, .nosearch](search/folders.md) | Folders read, Names only, .nosearch, text_exclude |
| [Cloud files: OneDrive, Dropbox, Google Drive, Proton Drive, iCloud](search/cloud-files.md) | Online-only files found by name and never downloaded, the cloud glyph, Download and preview, `cloud` and `cloud_read`, per system |
| [Removable disks](search/removable-disks.md) | Text kept while unplugged, found again at any mount point |
| [Search by meaning](search/meaning.md) | The built-in multilingual model, turning it on and off, what you see, how it works, how fast it is here (*Measure speed*, `coxswain --meaning bench`) |
| [Long files: sample or everything](search/long-files.md) | Sample (first 4 MB of text, 256 passages spread over the file) or Everything (all the text up to 256 MB, every passage), in Settings or per folder from the action menu; the cost said first; back to Sample reads nothing again |
| [Search by meaning on a server: Ollama, Lemonade, LM Studio](search/servers.md) | Ollama, Lemonade, LM Studio, any OpenAI-compatible server, API keys, privacy |
| [Ask: questions answered from your files](search/ask.md) | The Ask row of Find (Ctrl+Enter): your chat model answers from the closest passages, citing them, in place of the list |
| [Ask about code](search/ask-code.md) | Code read as code: passages cut at functions and classes with their lines, named after their item; a map of a project (files, public items, dependencies) for questions about it as a whole; any language |
| [Ask without a server: the built-in chat model](search/ask-builtin.md) | Qwen3 1.7B, 4B Instruct or 14B built in: the download, Metal on a Mac and the processor elsewhere, loaded in the helper and let go when idle, speed, `builtin:` in `ask_model` |
| [Built-in models](search/models.md) | The models on the disk, their folder, loaded or not and where, last used; unload, delete, delete all not in use, `coxswain --models` |
| [The search helper](search/helper.md) | One process for all windows, privacy of its connection, starting with the session, taken over after an upgrade moves the program |
| [Battery](search/battery.md) | Reading pauses on battery, Read now reads anyway |
| [Search settings](search/settings.md) | Every item of Settings → Finding files (the status, the levels, Details), its config.toml key, and the terminal flags |

## [The preview pane](previews/README.md)

| Page | What it covers |
|---|---|
| [The preview pane](previews/README.md) | Opening and closing it, what it shows, the switches, every format with its page, keys; desktop-only and why |
| [Text and code](previews/text-and-code.md) | Highlighted code, hex dumps, the git diff (File / Diff), Markdown with Mermaid and math |
| [Logs: follow, filter, columns](previews/logs.md) | Logs, JSON Lines and big text files of any size in both apps: coloured by level, followed as written (stop at errors), filtered by level, text or `name=value`, fields as columns, stack traces folded; JSON Lines, logfmt, access logs, syslog, W3C |
| [Documents: PDF, Word, EPUB, notebooks, mail, calendars](previews/documents.md) | PDF (and the line offering to make a scan searchable), Word .docx, EPUB, Jupyter notebooks, e-mail, AsciiDoc, reStructuredText, Typst, PostScript, XPS, calendars and contacts |
| [HTML pages, sandboxed](previews/html.md) | HTML files shown as sandboxed pages: what is allowed and blocked, scripts, the network, Rendered / Source |
| [PowerPoint and Office: quick view and LibreOffice's exact view](previews/office.md) | PowerPoint quick view drawn in the app, LibreOffice's exact view after it, every other Office format, old ones (Works, Write, WordPerfect, Lotus 1-2-3, StarOffice, AbiWord, iWork) and Windows clip art (WMF, EMF); LibreOffice installed or Gotenberg's image |
| [Data: trees, spreadsheets, databases and certificates](previews/data.md) | JSON/YAML/TOML trees, spreadsheets and CSV, SQLite, Parquet, DuckDB, certificates, property lists, Coxswain's own index.bin and search.db |
| [Cryptography bills of materials](previews/bom.md) | CycloneDX CBOMs as a rated tree or sunburst, with filters and a compare of two scans, in both apps |
| [Build provenance](previews/provenance.md) | SLSA and in-toto provenance as inputs → build → outputs: who signed, do the files here match, is the commit in your checkout, two builds compared; in both apps |
| [Chess games](previews/chess.md) | PGN files (also .pgn.gz, .pgn.zst), SCID databases (.si4, .si5) and ChessBase databases (.cbh, .cbv) as a table of games to filter and sort, a game on a board with its moves, variations, comments and their arrows (Alt+K, F3 in the terminal app), EPD and FEN positions, Polyglot opening books' moves for each position, figurines or letters, the board's colours, Find by player or opening, [chess] |
| [Game pieces in the terminal](previews/game-pieces.md) | The terminal app's chess, draughts, Go, shogi and xiangqi pieces as the desktop app's pictures where the terminal shows them (kitty graphics, sixel, Windows Terminal), else drawn from block characters: octants, sextants, quadrants or half blocks, chosen by the terminal or in Settings; Go stones, shogi tiles and xiangqi discs with their names as text; figurines on a small board, [chess] pieces |
| [Chess: playing on and the engine](previews/chess-play.md) | Moves played from any position of a game, an EPD position or a book (a click on a piece, then a square; m in the terminal app), kept as your line and saved only as a new PGN file (s), an installed UCI engine's best lines and evaluation (a, b), each stepped through without playing it (1–5, → ←), a whole game analysed with an evaluation bar, a graph and ?! ? ?? marks, saved annotated (g, w), the engines Coxswain knows with their install lines, Test engine and the engine's own options (threads, hash, strength, network file) per engine, a time, depth or node limit, [chess] analysis, engine, engine_limit, engine_time, engine_depth, engine_nodes, engine_lines, review_limit, review_time, review_depth, review_nodes, [chess.engines] |
| [Go games](previews/go.md) | SGF files as a list of games (players, ranks, komi, handicap, result), a game on a board with its captures, variations and comments (Alt+K, F3 in the terminal app), Find by player or event |
| [Draughts games](previews/draughts.md) | PDN files in the chess table of games, a game on a numbered 10×10 or 8×8 board with its captures, kings, variations and comments (Alt+K, F3 in the terminal app); international and English draughts (checkers) by the GameType tag, Find by player or event |
| [Xiangqi games](previews/xiangqi.md) | Chinese chess in PGN files (tag `Game "Chinese Chess"`) and DhtmlXQ games (the xiangqi websites' format, inside a zip too) in the chess table of games, a game on a board with the river and palaces, the pieces as red and black characters, moves in ICCS, WXF or Chinese (Alt+K, F3 in the terminal app), Find by player or event |
| [Shogi games](previews/shogi.md) | KIF and CSA files in the chess table of games, a game on a 9×9 board with the pieces in hand, captures, drops, promotions, variations and comments (Alt+K, F3 in the terminal app), handicaps and board diagrams, Find by player or event |
| [Bridge deals](previews/bridge.md) | PBN files as a table of deals (pairs, contract, result), a deal as four hands round the table with its auction, stepped through trick by trick (Alt+K, F3 in the terminal app), Find by player or event |
| [Neural network models](previews/neural-networks.md) | ONNX, TensorFlow Lite, Core ML (also .mlpackage) and Keras models: format, producer, operator set, inputs and outputs with shapes, nodes and parameters in both apps (F3 and Alt+Enter in the terminal app); the graph drawn by Netron in the desktop app, offline and sandboxed; no pickles, no PyTorch |
| [Media and files: pictures, video, audio, fonts, archives, folders](previews/media.md) | Pictures, video, audio, fonts, archives listed (and files inside archives), folders, facts under a file; with ffmpeg and ImageMagick the video and sound the player cannot play, HEIC, GIMP and RAW photos, video thumbnails |
| [Old pictures and files](previews/old-formats.md) | TIFF with its pages, TGA, Netpbm, DDS, HDR, OpenEXR, QOI, JPEG XL, Amiga IFF, PCX, XPM, XBM and Photoshop pictures; CBZ comics page by page, mailboxes opened as folders of messages, Outlook .msg, dBase tables, tracker music facts; in both apps |
| [E-books: MOBI, Kindle, FictionBook, LIT and Palm](previews/ebooks.md) | MOBI, Kindle (AZW, AZW3), FictionBook, LIT and Palm books through calibre: cover, title, authors and first pages, their words in Find, Convert e-book to EPUB, AZW3 or PDF, books with DRM left alone; opt-in, installed calibre or its container; both apps |
| [Diagrams: draw.io, Mermaid, Graphviz, PlantUML, D2 and more](previews/diagrams.md) | Draw.io, Mermaid, Graphviz and PlantUML in the preview; D2, ditaa, svgbob, Pikchr, nomnoml, WaveDrom, Vega, Vega-Lite, DBML, erd and bytefield by their programs or Kroki's image |
| [LaTeX projects](previews/latex.md) | LaTeX: which file is the document, the project, the engine, building by itself, another engine when one fails, errors |
| [Geodata: maps, facts and Convert geodata](previews/geodata.md) | GeoPackage, shapefiles, GeoJSON, KML, GPX and GeoTIFF as a map of their own shapes, their layers, coordinate system and extent, a GPX track's length and time; Convert geodata to GeoPackage, GeoJSON, a shapefile, KML, GPX, COG or PNG; by GDAL installed or in its container; both apps |
| [OpenSCAD models: pictures and Export 3D model](previews/openscad.md) | `.scad` models as a picture of the part OpenSCAD makes (a flat one as its outline), Rendered / Source, Export 3D model as STL or 3MF; by OpenSCAD installed or in its container; both apps |
| [KiCad: schematics, boards and Export from KiCad](previews/kicad.md) | KiCad schematics sheet by sheet and boards layer by layer as a PDF, a board in 3D as its thumbnail, Export from KiCad to PDF, SVG, a bill of materials (CSV) or Gerbers; by kicad-cli installed or in KiCad's container; both apps |
| [Previews made by tools](previews/tools.md) | The engine buttons, how rendering works, the preview cache and Clear, [preview] |
| [Containers](previews/containers.md) | Podman or docker: what a container may do, what each image gives and costs, pulling and removing images, keeping them up to date, images in Settings |
| [Safety, speed and limits](previews/safety.md) | What a preview never does, what reaches the network, speed, and every size limit |

## [Files](files/README.md)

| Page | What it covers |
|---|---|
| [Files](files/README.md) | The area, every page, the file keys in both apps |
| [Copy (F5), and when something goes wrong](files/copy.md) | Copy (F5): targets, never overwriting, merged folders, what a failure says |
| [Move and rename (F6)](files/move-and-rename.md) | Moving, renaming in place, across disks, into archives |
| [New folder (F7)](files/new-folder.md) | One folder or a whole path, also inside archives |
| [Delete: trash (F8) or for good (Shift+F8)](files/delete.md) | Trash (F8), for good (Shift+F8), taking out of an archive, turning the question off |
| [Undo (Ctrl+Z)](files/undo.md) | Ctrl+Z, both apps: the last 20 copies, moves, renames, new folders, trashings, packs, extracts, find-and-replaces and changes of permissions and dates; checked first, never overwrites; not Shift+F8 |
| [Clipboard: Ctrl+C, Ctrl+X, Ctrl+V](files/clipboard.md) | Ctrl+C / Ctrl+X / Ctrl+V shared with other file managers, name (2) |
| [Drag and drop](files/drag-and-drop.md) | Out to other apps (out of archives too), between panes, onto folders, in; the copy/move menu, Ctrl and Shift |
| [Batch rename (Ctrl+M)](files/batch-rename.md) | Batch rename (Ctrl+M, desktop): regex, groups, {n:3} counter, live preview, conflicts |
| [Find and replace across files (Alt+R)](files/find-and-replace.md) | Alt+R, both apps: text or a regex in the marked files or Find's results; every change previewed and untickable; encoding, line endings and permissions kept; one undo |
| [Archives as folders](files/archives.md) | Zip/tar/7z opened with Enter; copy in, out, between; formats; what is rewritten; why not RAR; limits |
| [Pack (Alt+F5) and extract (Ctrl+E)](files/pack-and-extract.md) | Pack (Alt+F5) into any archive format by its name, extract (Ctrl+E) into a new folder |
| [Passwords for encrypted zip and 7z](files/archive-passwords.md) | Passwords for locked zip and 7z: when asked, kept in memory for the app run, never saved |
| [Disk images, CHM help files and CBR comics](files/disk-images.md) | Facts of .iso, .dmg, .vhd, .vhdx, .vmdk, .qcow2 and raw images in the preview; opened like folders, read-only, with an installed 7-Zip (opt-in), never mounted |
| [Container images](files/container-images.md) | A docker save, podman save or OCI image opened with Enter as one read-only folder of its merged layers (whiteouts honoured); tags, platforms, layers, entrypoint in the preview and Properties |
| [Your local models, by name](files/local-models.md) | Ollama blobs (`sha256-…`) shown as `llama3.2:3b`, Hugging Face `models--org--name` as `org/name`, in the panels and Space; GGUF and safetensors facts (architecture, parameters, quantisation, layers), memory to load and whether it fits; pickles never opened |
| [Properties and permissions](files/properties.md) | Properties (Alt+Enter, both apps): size, dates, owner, permissions and read-only; ZFS dataset, FreeBSD package, file flags (chflags) |
| [Permissions and dates in bulk (Alt+M)](files/permissions-and-dates.md) | Alt+M, both apps: chmod-style bits (644, u+x,go-w, a+X) or read-only and hidden on Windows, and modified dates (now, a date, another file's) for the marked files, into folders if asked; planned first; one undo |
| [Finding duplicates](files/duplicates.md) | Files and whole folders, across disks, safe removal to the trash |
| [Compare files (Shift+F2)](files/compare-files.md) | Shift+F2, both apps: side by side or one under the other, changed words, spaces and case set aside, next change, copy a change across and save; documents by their text, pictures by their pixels (overlay and difference in the desktop app), other files as hex |
| [Compare folders (Ctrl+F2)](files/compare-folders.md) | Ctrl+F2, both apps: two folders recursively, by size and date or byte by byte; + > < ≠ = in both panels as found; differences only; mark differences and F5; make one side like the other after a plan (to the bin, Ctrl+Z); links compared as links; archives, images, snapshots and histories read-only; Stop |
| [ZFS snapshots as folders](files/zfs-snapshots.md) | Alt+Z: a dataset's snapshots, newest first, browsed read-only; diff against now, F5 copies back; the ZFS line in the footer |
| [Make PDF searchable (Alt+P)](files/searchable-pdf.md) | A copy of a scanned PDF with its words in it (`name.searchable.pdf`), by OCRmyPDF installed or in its container; never over the original; progress and Stop; both apps |
| [Convert video or audio](files/convert-media.md) | MP4, MP3 or FLAC copies of videos and songs, their sound, a clip, by ffmpeg installed or in its container; next to the original, never over it; progress and Stop; both apps |
| [Convert or edit pictures](files/edit-pictures.md) | JPEG, PNG or WebP copies of photos, smaller, without the location, turned, by ImageMagick in its sealed container or installed under a policy; next to the original; both apps |
| [Checksums (Alt+H)](files/checksums.md) | SHA256SUMS, SHA512SUMS or B3SUMS of the marked files and folders, in the lines sha256sum and b3sum read; Enter on a list checks it (OK, changed, missing, not read) and marks what changed; GNU and BSD forms; progress and Stop; both apps |
| [Split and join (Alt+X)](files/split-and-join.md) | A big file cut into parts of a chosen size (100 MB, CD, FAT32 stick, DVD, typed) as name.001 … with name.sha256; Enter on name.001 joins and checks them; never over a file; progress and Stop, nothing half made left; both apps |
| [Build PDF of AsciiDoc](files/asciidoc-pdf.md) | A PDF of an AsciiDoc document next to it, by Asciidoctor PDF installed or in its container (about 665 MB); diagrams drawn by the preview's programs; no remote includes or pictures; both apps |
| [Export draw.io diagram](files/drawio-export.md) | PNG or SVG of each page, or one PDF, next to a draw.io diagram (also inside `.drawio.svg`, `.drawio.png`), by draw.io only in its sealed container (about 560 MB, opt-in, podman or docker); thumbnails in the grid view; both apps |
| [Scan for viruses (Alt+I)](files/virus-scan.md) | A file, the marked files or a folder scanned by ClamAV in a container without network, only when asked (opt-in); its database from database.clamav.net when a day old; each file found left, binned or quarantined, never deleted by itself; both apps |

## [Customising](customise/README.md)

| Page | What it covers |
|---|---|
| [Customising](customise/README.md) | The Settings window, themes, looks, languages, keys, glyphs and fonts, with the main keys |
| [The Settings window](customise/settings.md) | Opening it (Ctrl+, or the gear in the desktop app, F12 in the terminal app, Shift+F10, F9, `--settings=search` or `--settings=search_meaning`), its areas from Overview to Privacy and updates, Find a setting, every item with its config.toml key, how saving keeps comments, the terminal app's full-screen Settings (F12, `--settings`) and flags |
| [Themes](customise/themes.md) | The 33 built-in themes in six groups, picking one in each app (Settings → Looks, F12 in the terminal app, F9 "Theme: …", `theme` / `[gui] theme`), what the terminal app takes |
| [Looks](customise/looks.md) | The desktop app's corners, bevels, title bars and era fonts per theme, `look =` in your own theme |
| [Your own theme and the colour slots](customise/own-theme.md) | Your own theme: `[themes.<name>]`, starting from --dump-config, colour names vs #rrggbb, every colour slot and where each app uses it |
| [Languages](customise/languages.md) | The 31 languages with flags, by region, how Automatic picks one, right to left in Hebrew and Persian, what is translated, improving a translation |
| [Changing keys](customise/keys.md) | `[keys]`, key names, rules, every action with its default, keys that cannot be changed, terminal limits |
| [Glyphs and fonts](customise/glyphs-and-fonts.md) | Nerd Font or ASCII glyphs, `[glyph_set]`, file icons, the interface/monospaced/icon fonts, text size and line height |

## [Reference](reference/README.md)

| Page | What it covers |
|---|---|
| [Reference](reference/README.md) | The area index, its pages and the keys that reach them |
| [The terminal app](reference/terminal-app.md) | What it has, what only the desktop app has and why, differences, archives and search by meaning in the terminal, the terminal it needs |
| [Command-line flags](reference/command-line-flags.md) | Every flag of coxswain and coxswain-gui: folders, --paths, --dump-config, --config-path, --meaning, --index-service, --settings, --duplicates, --index-helper, exit status |
| [Configuration: every key](reference/configuration.md) | Config.toml: every key with type, default and reader; which Settings item writes it; what has no key |
| [Privacy: what stays, what can leave](reference/privacy.md) | What stays on your machine, every case where something can leave it, and how to stop it |
| [Update checks](reference/updates.md) | The update check: what it sends, what each app shows, the upgrade command, turning it off |
| [Where things are kept](reference/where-things-are-kept.md) | Config, state and cache folders on each system, every file in them, what is safe to delete, removing everything |
| [Disk use](reference/disk-use.md) | Settings → Privacy and updates → Disk use and coxswain --disk: each place's size, where, what clearing costs, Clear; Tectonic's cache and container images Coxswain caused; clear everything that is built again |
| [Security](reference/security.md) | Dependencies: how they are chosen and updated, advisory and licence checks on every change and weekly, the bundled viewers, checking a download, reporting a problem |
| [Licences and bills of materials](reference/bills-of-materials.md) | The SBOMs, the CBOM and the third-party notices each release carries, the licence checks, the cryptography both apps use |
| [Performance](reference/performance.md) | What keeps each app quick, the numbers for 100,000 files, a folder of a million and a million names, and how to measure again |

## [Systems](systems/README.md)

| Page | What it covers |
|---|---|
| [Systems](systems/README.md) | What is particular to each system, in one page each: FreeBSD first, then the other BSDs and illumos, Linux, Android, ChromeOS, macOS and Windows |
| [FreeBSD](systems/freebsd.md) | Both apps on FreeBSD: one-line install, packages, the search helper without systemd (autostart, rc.d, login shell), search by meaning, ZFS snapshots and facts, a file's package, file flags, boot environments and jails, differences, updating, the desktop app's experimental status, other BSDs |
| [NetBSD](systems/netbsd.md) | Both apps on NetBSD 10 (the desktop app experimental): one-line install with ftp, the packages from pkgin, the search helper from rc.d, kqueue within the open-file limit, envstat for the battery |
| [OpenBSD](systems/openbsd.md) | Both apps on OpenBSD 7.9 (the desktop app experimental): one-line install, pkg_add, OpenBSD's own Rust, the search helper with rcctl, login.conf limits (open files, datasize) and what Coxswain does about them |
| DragonFly BSD | Not supported; its Rust (1.85 in DPorts) is too old for Coxswain's dependencies |
| [illumos](systems/illumos.md) | The terminal app on OmniOS and OpenIndiana: one-line install with curl, the search helper as an SMF service, ZFS snapshots and datasets, event ports for watching, zones, why there is no desktop build |
| [TrueNAS](systems/truenas.md) | The terminal app on a TrueNAS box over SSH (Community Edition with the Linux build, CORE with the FreeBSD build) into your home: snapshots of every dataset, leaving the system datasets alone, indexing the shares |
| [Linux on ARM](systems/linux-arm.md) | Both apps on 64-bit ARM Linux (Raspberry Pi OS, Asahi, ARM servers): the files, what they need, installing, the Pi, Asahi, servers, search by meaning on ARM |
| [Flatpak](systems/flatpak.md) | The desktop app as a Flatpak (io.github.mwo_dk.Coxswain): --filesystem=host and flatpak-spawn, the editor, commands and preview programs on the host, the search helper inside the sandbox, autostart, its own config folder, updating, building with flatpak-builder |
| [Nix](systems/nix.md) | The flake for both apps (`nix run github:mwo-dk/coxswain`), profile, NixOS and Home Manager installs, the desktop app's wrapping, updating, nixpkgs and the flake |
| [Termux on Android](systems/termux.md) | The terminal app in Termux: `pkg install coxswain` (or `cargo install --locked coxswain` until the package is in), the phone's folders with termux-setup-storage and Alt+F1, termux-open, Termux:API for clipboard and battery, the helper without a session service, F8 without a trash, F-keys on the extra keys row, updating, the package recipe and its CI build |
| [ChromeOS](systems/chromeos.md) | Both apps in ChromeOS's Linux: which .deb, installing, sharing ChromeOS folders, the helper, no GPU for meaning search, what was checked |
| [macOS](systems/macos.md) | The folder prompts (TCC) and what to answer, what is never read on a Mac (~/Library but iCloud Drive, Photos and Music libraries), Full Disk Access, ad-hoc signing and asking again after updates, search by meaning on the GPU without a server |
| [Windows on ARM](systems/windows-arm.md) | Native ARM64 builds of both apps: which file, installing, WinGet, from the x64 build to the ARM one, search by meaning |

## [Questions, collected](faq.md)

The common questions from every page, linked to their full answers.

Installing, and building from source: [the README](../README.md#install) and [install/INSTALL.md](../install/INSTALL.md).

---
[← Previous: README](../README.md) · [Next: Panels and keys →](panels/README.md)