The wheel's urna command
The urna console command installed by the Python wheel, its four read-only verbs, how it differs from the Rust binary, and the PATH collision between the two.
The urna wheel installs a console command also named urna. It is a small Python script over the library, with four read-only verbs: validate, inspect, stats and search. It is not the Rust binary: it has no ask, retrieve, build, cite, setup or doctor.
Usage
urna validate FILE
urna inspect FILE
urna stats FILE
urna search FILE QUERY [-k K]Run it without installing anything into your environment:
uvx --from urna urna validate corpus.urna
pipx run --spec urna urna validate corpus.urnaIn a repo checkout, the same script is python python/urna_cli.py <verb>.
Verbs
| Verb | Arguments | Does |
|---|---|---|
validate | FILE | opens the file and runs UrnaFile.validate() |
inspect | FILE | prints UrnaFile.inspect() as JSON, indented by 2 |
stats | FILE | prints 11 fields from the UrnaFile properties |
search | FILE QUERY | exact search. QUERY is a JSON array of floats with the file's dimension |
Options
| Option | Default | Description |
|---|---|---|
-k K | 10 | search only: hits to return. There is no long form --k |
-h, --help | print help |
There is no --version, no --json and no color.
Output
Everything goes to stdout, except errors, which go to stderr as urna: error: <message>.
validate prints the two hashes:
$ urna validate quickstart.urna
ok: quickstart.urna
file_hash: sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832
content_hash: sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09dfstats prints 11 lines:
$ urna stats quickstart.urna
file: quickstart.urna
embedding_dim: 256
n_embeddings: 12
dtype: float32
simd_backend: neon
has_ann: True
has_bm25: True
has_graph: True
model_hash: sha256:8f2eb91a754b4da59cdd8223d0ba196185fed1bb6f092fd2be0ff02b893b1c98
file_hash: sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832
content_hash: sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09dfsearch prints one line per hit, [rank] score=<6 decimals> chunk_id=<id> citation=<urna://...>. Here notes.urna is the three-chunk file built in Use urna from Python:
$ urna search notes.urna "$(python embed.py network)" -k 2
[1] score=0.218242 chunk_id=sha256:165ebb7b21496454d55635d169568cc86275a8b5f882e7f00b6597c7f3829911 citation=urna://sha256:3b77075fbd3aea4eb06d48771d9ef1586276b904a07524f395dd247c37168b1b/sha256:165ebb7b21496454d55635d169568cc86275a8b5f882e7f00b6597c7f3829911
[2] score=0.114246 chunk_id=sha256:d1153ebf5e37797ecc23dd485d999849d1cc87e452a2e150a496b9eb3ad40941 citation=urna://sha256:3b77075fbd3aea4eb06d48771d9ef1586276b904a07524f395dd247c37168b1b/sha256:d1153ebf5e37797ecc23dd485d999849d1cc87e452a2e150a496b9eb3ad40941Here embed.py is any script that prints a potion vector as JSON, for example:
import json
import sys
from urna.embed_potion import potion_embedder
print(json.dumps(potion_embedder().embed_texts([sys.argv[1]])[0]))Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | any error while running the verb: bad JSON, a missing or corrupt file, a dimension mismatch, invalid k: 0. The message is on stderr |
2 | usage error: no verb, an unknown verb such as ask, a missing argument |
$ urna search notes.urna '[0.5, 0.5]'
urna: error: dimension mismatch: expected 256, got 2
$ urna ask notes.urna "question"
urna: error: argument cmd: invalid choice: 'ask' (choose from validate, inspect, stats, search)The first exits 1, the second 2 (after the usage line).
Compared with the Rust binary
Wheel urna | Rust urna | |
|---|---|---|
validate | the reader checks only | the reader checks plus a SHA-256 proof of every inlined blob, one line per check. See urna validate |
inspect | always JSON | human layout, --json for JSON. See urna inspect |
stats | 11 fields, no size, no spaces | size, dims, mrl_dim and full_dim, metric, index type, rerank, model, chunker, capabilities, the section table, the spaces. See urna stats |
search | exact, one short line per hit, -k | exact, with index type, recall, timing and full hit lines, -k or --k. See urna search |
ask, retrieve, build, cite | absent | present |
search-ann, search-graph, search-space, search-text, media, benchmark, doctor | absent | present |
setup, tui, --version | absent | present |
The wheel has 4 verbs, the binary 17. The Python method UrnaFile.retrieve exists in the wheel; the urna retrieve verb does not. To query by text from the terminal, install the binary: see Installation.
Two commands named urna
The wheel and every other install channel put a command called urna on your PATH. Whichever comes first wins. An activated virtualenv with the wheel hides the full CLI, and urna setup or urna ask then fail with exit code 2 and invalid choice.
On Linux, pip install --user writes console scripts to ~/.local/bin, the same directory the install one-liner puts the Rust binary in, so one can overwrite the other.
Check which one you are running:
which -a urna
urna --version # the Rust binary prints "urna 0.5.1"; the wheel command exits 2 with a usage errorTo keep both, leave the Rust binary first on PATH and call the wheel command by its full path (for example .venv/bin/urna) or through uvx --from urna urna ....
Errors
The exceptions urna raises in Python, when each one happens, and the exact messages for opening, querying, the model gate and urna.build.
Rust crates
The urna-format and urna-runtime crates: what to depend on, the builder, the reader, MmapUrnaFile, its search functions, result types and a runnable example.