The terminal explorer

urna tui is a full-screen terminal explorer. It opens a .urna file, shows its manifest and section table, answers questions against it with the same offline embedder and model gate as urna ask, and runs the install checks of urna doctor. It needs the binary from a package channel or the one-liners; the pip wheel has no explorer.

Open itCopy Anchor Link

urna tui                 # start on the home tab
urna tui corpus.urna     # start loading this file at once
urna                     # same as urna tui, when run in a terminal

A bare urna opens the explorer only when both stdin and stdout are terminals. In a pipe or a script it prints the help and exits 2. The window needs at least 50 columns by 16 rows; below that it shows "urna tui needs at least 50x16" until you resize.

The explorer captures the mouse. To select text with the mouse, hold the modifier your terminal uses to bypass mouse reporting (Shift in most terminals).

LayoutCopy Anchor Link

The top three rows are the header: the urna mark, the tab pills (home, corpus, ask, health) and, on the right, the open corpus as <name> · <size>, a spinner while one loads, or "no corpus open". Tabs that do not fit the width are dropped from the header; the keys still reach them. The bottom row lists the keys of the current tab. Notices appear at the top right for about three seconds.

TabsCopy Anchor Link

HomeCopy Anchor Link

Lists up to nine .urna files from the working directory and its non-hidden subdirectories one level down, largest first, numbered 1 to 9. With none found it shows o open a .urna. It also shows rows for s setup and h health.

CorpusCopy Anchor Link

Opening a file switches here. The top block reads the manifest: chunks, dim, dtype, metric and score type, index type and rerank policy, model, a short model_hash, size, short file_hash and content_hash. Below it are the validation verdict ("valid: checksums, hashes, contract" or the error), the citation form urna://<content_hash>/<chunk_id>, and the section table: id, name, encoding, size and a log-scaled bar.

Loading reads the whole file into memory to validate it, so opening a multi-gigabyte corpus costs that much RAM for a moment. The check covers the header, section checksums, hashes, embedding values and the search contract. It skips the per-blob hash check that urna validate runs on inlined media, so run urna validate when that matters.

AskCopy Anchor Link

Type a question and press Enter. The query is embedded offline, checked against the corpus's model_hash, and searched for the top 10 hits. Each hit shows its exact-rerank cosine score with a bar; the selected hit shows its stored canonical text, its urna:// citation and its source. The status line reads N hits for "q" · T ms or the error.

Two errors come with a fix:

HealthCopy Anchor Link

Runs the doctor checks in the background: at startup, again each time you enter the tab (unless a run is in progress), and on r. The tag reads "every check passes" or exit N with the doctor code. When a run ends with failures while you are on the tab, a notice says how many failed and that s runs setup.

KeysCopy Anchor Link

Keys that work on every tab, as long as the file picker is closed:

On home, corpus and health, letters are commands:

On the ask tab, letters are the query, so quitting is Ctrl+Q (or Ctrl+C) and opening a file is Ctrl+O:

The file pickerCopy Anchor Link

The picker lists directories and .urna files only, starting in the directory you launched from. After you change directory, the cursor lands on the first .urna there. While it is open it takes every key: Ctrl+C does not quit, and Ctrl+Q closes the picker like q instead of quitting.

Running setup from the explorerCopy Anchor Link

s hands the terminal to the interactive urna setup with default options, then reopens the explorer with the same corpus. The explorer ignores setup's exit code; the health tab shows the result. For flags such as --no-python, quit and run urna setup directly.

Colors and linksCopy Anchor Link

The explorer draws in 24-bit color and converts the finished frame to what the terminal supports. It decides in this order:

1. NO_COLOR set to a non-empty value: no color (an empty NO_COLOR is ignored).
2. URNA_COLOR: none for no color, 256 for the xterm 256-color palette, truecolor or 24bit for 24-bit. Other values fall through.
3. 24-bit when COLORTERM contains truecolor or 24bit, TERM_PROGRAM contains iterm, wezterm, vscode, ghostty, hyper, warp, tabby, rio or zed, TERM contains kitty, alacritty, direct, ghostty or foot, or WT_SESSION is set.
4. Otherwise the 256-color palette. There is no 16-color mode.

In 256-color mode each color maps to the nearest index from 16 to 255, so the 16 colors your terminal theme controls are never used. With no color, bold and underline remain.

Links (such as the urna.dev link on the home tab) are OSC 8 hyperlinks. On Windows they are plain text unless WT_SESSION is set, because older consoles print the escape codes raw.

Exit codes and arguments are in urna tui.