Reference overview
What the urna reference covers (CLI verbs, build spec, models, Python, Rust, file format, environment) and the conventions every verb follows.
The reference tab describes every command, spec key, API and file-format detail of urna 0.5.1, one page per item. Use it to look up a flag, a key or an exit code; the Docs tab explains concepts and walks through tasks.
What is in this tab
| Section | Covers |
|---|---|
| CLI | The 17 verbs of the urna binary: usage, every flag with its default, output, exit codes and examples. |
| Build spec | The corpus.toml file that urna build reads: [source], [[models]], [media], [build] and [output], and the files a build writes. |
| Models and presets | The model registry a spec picks from, and the build presets that set a file's encoding, dtype and indices. |
| Python | The urna module: UrnaFile, hit types, urna.build, embedders, the builder pipeline of a checkout, errors and the wheel's urna command. |
| Rust crates | urna-format (read and write the container) and urna-runtime (open and search). |
| File format v1 | The on-disk layout: sections, encodings, hashes and citation ids, the manifest and compatibility. |
| Environment | Environment variables, paths and resolution order, exit codes, typed errors and the query embedder protocol. |
Verb groups
urna --help sorts the 17 verbs into three groups.
| Group | Verbs | What they do |
|---|---|---|
| engine | inspect, validate, stats, media, search, search-ann, search-graph, search-space, search-text, benchmark, cite, doctor | Take a file, and a query vector where one is needed, and read the file directly. Two of them run Python despite the group's "no python" label in urna --help: search-text embeds the query with a Python script, and doctor, which takes no file, runs a test embed. |
| agent | ask, retrieve, build | Take text or a build spec. ask and retrieve embed the question with the offline Python embedder, check its model_hash and return cited text; build launches the Python forge from a repository checkout. |
| setup | setup, tui | The installer that lays down the embedder and a Python env, and the terminal explorer. Both exist only in binaries built with the default tui feature. |
The CLI overview lists every verb with a link to its page.
Conventions
Arguments
A corpus is always the first positional argument, <FILE>. search, search-ann, search-graph and search-space take the query as a JSON array of floats at the file's dimension (or the space's dimension); ask, retrieve and search-text take plain text. Every verb that returns hits takes -k, with a default of 10.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | An error. The message goes to stderr as Error: <message>: a missing or corrupt file, a citation that does not match the file, a query embedder that fails the model gate. |
2 | A usage error: an unknown verb or flag, or a missing argument. A bare urna with no terminal also prints the help and exits 2. |
A few verbs add their own codes. doctor exits 2 to 6 for the first failing check, setup adds 10 to 14 and 130 for a cancel, and build passes through the forge's 1, 2 (spec error) and 4 (model registry error). Exit codes lists them all.
stdout and stderr
Results go to stdout and errors to stderr. Verbs that start a Python process (ask, retrieve, search-text, build, doctor) print the interpreter they chose on stderr, as [urna] embedder interpreter: <path>, so the stdout of retrieve stays machine-readable. build streams the forge's own output unchanged. doctor and setup color their output only when stdout is a terminal, and NO_COLOR or URNA_COLOR=none turn color off.
JSON output
Three verbs print JSON on stdout:
urna retrieveprints one hit per line with--format jsonl(the default) or one array with--format json. Each hit haschunk_id,score,score_type,source_uri,offset_start,offset_end,citation_id,text,file_hash,content_hashandrerank_source.urna inspect --jsonprints the header fields, the manifest, the section table, media blobs, named spaces and both hashes.urna buildprints one JSON object summarizing the build.[forge]notices can come before it on stdout, so a script should parse the last JSON object.
The other verbs print text meant for people.