CLI overview
The 17 verbs of the urna command line in three groups, the five that cover the whole loop, the global flags, and what a bare urna does on a terminal.
urna is a single binary with 17 verbs. This page is the map of urna --help: the five verbs that cover the build, query and verify loop, every verb by group with a link to its page, and the flags that apply to all of them.
urna: single-file, memory-mapped, hash-verified vector database with stable citations
Usage: urna [COMMAND]Start here
These five verbs cover the loop from rows to a verified, cited answer.
| Verb | Role | In and out | Example |
|---|---|---|---|
build | Creates the base | Rows and an embedding model in, one .urna out | urna build --spec corpus.toml |
ask | Queries it | Text in, cited answer out | urna ask corpus.urna "question" |
retrieve | Results for a program | JSON or JSON lines of cited spans, exact score | urna retrieve corpus.urna "question" --format jsonl |
cite | Resolves the source | A urna:// citation back to its stored text | urna cite corpus.urna 'urna://...' |
validate | Proves the file | Every checksum, every hash, the search contract | urna validate corpus.urna |
build needs a checkout of the repository; the other four work with the installed binary on corpora built with the default potion model. See Known limits.
All verbs
engine
Engine verbs take a file, plus a query vector where one is needed, and read the file directly. search-text and doctor are the exceptions: both run Python, and doctor takes no file.
| Verb | What it does |
|---|---|
inspect | Prints the header, section table, manifest and hashes; --json for a JSON document. |
validate | Checks the magic, every checksum, the hashes, the manifest and the search contract. |
stats | Prints size, chunk count, dimension, dtype, model, index type and the section table. |
media | Lists the media blobs a corpus references; --export writes the inlined ones back to files, hash-verified. |
search | Exact search with a query vector given as a JSON array. |
search-ann | Forces the HNSW path; falls back to exact search when the file has no HNSW index. |
search-graph | Seeds from the exact top results, expands along the chunk graph, reranks by exact cosine. |
search-space | Exact search over one named space, with a vector from that space's model. |
search-text | Embeds a text query with a sentence-transformers script, checks model_hash, then searches. |
benchmark | Times exact search, and optionally HNSW search, on random queries. |
cite | Resolves a urna://content_hash/chunk_id citation to the stored text and span. |
doctor | Checks the install: version, SIMD backend, Python, its dependencies and one offline test embed. |
agent
Agent verbs take text or a build spec and hand work to Python.
| Verb | What it does |
|---|---|
ask | Embeds the question offline, checks model_hash, searches and prints the cited stored text. |
retrieve | The same search as ask, printed as JSON or JSON lines for another program. |
build | Builds a corpus from a TOML or JSON spec by launching the forge in a repository checkout. |
setup
| Verb | What it does |
|---|---|
setup | Installs the offline embedder payload and a Python env with numpy and tokenizers, then runs the doctor checks. |
tui | Opens the terminal explorer: open a .urna, read its sections, ask it, check the install. |
setup and tui exist only in binaries built with the default tui feature. A cargo install urna --no-default-features build has neither.
urna help prints the help, and urna help <verb> the help of one verb.
Global flags
| Flag | Description |
|---|---|
-h, --help | Print the help of urna or of a verb. ask has a short (-h) and a long (--help) form. |
-V, --version | Print the version, for example urna 0.5.1. |
There are no other global flags. Output color follows the terminal and the NO_COLOR and URNA_COLOR variables; see Environment variables.
Running urna with no verb
On a terminal, a bare urna opens the terminal explorer, the same as urna tui. When stdin or stdout is not a terminal, for example in a script or a pipe, it prints the help and exits 2.
First run
Run urna setup once after installing. ask, retrieve and doctor need the offline embedder and a Python env with numpy and tokenizers. Homebrew, npm and cargo install the binary alone, and the one-line installers add the embedder but not the env; setup lays down whatever is missing and ends with the doctor checks. See Installation.
urna setupReference overview
What the urna reference covers (CLI verbs, build spec, models, Python, Rust, file format, environment) and the conventions every verb follows.
urna ask
Ask a .urna file a question in plain text and get the stored text of each hit with its urna:// citation, embedded offline and model-gated.