Quickstart

Nabu is operated from the command line and lives entirely under its own directory — plain files plus SQLite, no services. Initializing your own library takes five steps. The few house terms the output uses (shelf, core group, license class…) are defined in a short glossary at step 3, beside the first output that prints them.

Before you start

• Tested platform: macOS on Apple Silicon only. It is the one platform Nabu is developed and exercised on. Nothing in the core is known to be Mac-specific, so Linux may well work, but it is untested — as is Windows.
• You need Ruby 3.3 or newer and git. Check with ruby -v; if Ruby is missing or older, follow the official Ruby installation guide.
• Budget up to ten minutes for the whole quickstart path below. The four starter sources measure 693 MB on disk (7 November 2026), and the databases derived from them add roughly half that again. Most of the time is download, and the dictionary source dominates it.
• Room to grow: the full library currently occupies roughly 148 GB canonical + 193 GB of derived databases on the reference machine (measured 7 November 2026; OpenITI, ORACC and the NDL classical stacks dominate the canonical side) — growth is entirely at your discretion, shelf by shelf.

1. Clone

git clone https://github.com/arvicco/nabu
cd nabu

2. Install

bundle install

The dependency set is deliberately small (thor, sequel, sqlite3, nokogiri, faraday, plus test tooling). Configuration is optional: every key in config/nabu.yml has a working default, so a fresh checkout runs as-is.

3. Sync the starter shelf

bin/nabu quickstart

The words the output uses, in six lines:

• source — one upstream collection (a corpus, a treebank, a dictionary) as Nabu fetches it, named by a short slug such as sblgnt.
• shelf — a source as it sits in your library once synced: its fetched files plus the databases derived from them. The starter shelf is the four sources this step syncs.
• passage — the smallest citable unit of a text (a verse, a line, a treebank sentence), each with a stable urn:nabu:… address that bin/nabu show opens.
• core group — the small reference registries (languages and places) every library depends on; always synced first, automatically.
• desk (the CLI says axis) — a scholarly grouping of sources by field, from the Classicist’s to the Assyriologist’s.
• license class — the upstream license reduced to one label, carried by every passage and printed beside every result. The labels:

The full terms, source by source, are on Sources.

The command first syncs the core group (nabu-lects, nabu-places, and CIGS, the cuneiform site index: a few hundred KB total, always enabled; bin/nabu sync core re-runs just that sweep any time) — then the four curated starter sources, each through its normal fetch → load → index path, and ends by printing the first three commands to try. The starter set, with sizes measured from the live canonical tree on 7 November 2026:

The whole step fits the ten-minute budget above, per-source index builds included; the lexica download dominates, while sblgnt takes seconds, so a slow connection stretches the fetches and little else. The command is idempotent — re-running it is an ordinary re-sync — and one source’s failure never stops the rest: failures are reported at the end. bin/nabu quickstart --dry-run prints the set without syncing anything.

4. First marvels

The starter shelf lights the library’s three signature surfaces.

One verse across seven witnesses. bin/nabu align "MARK 2.3" renders the same verse in Greek (twice — PROIEL and SBLGNT), Latin, Gothic, Classical Armenian, Old Church Slavonic, and Old English, each with its license class.

The sample below is not a quickstart run. It was captured on 2026-07-11 from the maintainer’s full library, which holds more witnesses of this verse than the quickstart corpus — hence its “13 of 13”. On a fresh quickstart library the same command shows the seven starter witnesses; the other six (the English WEB, the Clementine Vulgate, and four further Old Church Slavonic manuscripts) arrive as you grow the library.

$ bin/nabu align "MARK 2.3"
MARK 2.3 — New Testament (parallel witnesses)
  13 of 13 witnesses attest this ref

greek-nt — The Greek New Testament [grc]   license: nc
  urn:nabu:proiel:greek-nt:6563
    καὶ ἔρχονται φέροντες πρὸς αὐτὸν παραλυτικὸν αἰρόμενον ὑπὸ τεσσάρων.

latin-nt — Jerome's Vulgate [lat]   license: nc
  urn:nabu:proiel:latin-nt:10368
    et venerunt ferentes ad eum paralyticum qui a quattuor portabatur

gothic-nt — The Gothic Bible [got]   license: nc
  urn:nabu:proiel:gothic-nt:37435
    jah qemun at imma usliþan bairandans, hafanana fram fidworim.

marianus — Codex Marianus [chu]   license: nc
  urn:nabu:proiel:marianus:36421
    Ꙇ придѫ къ немоу носѧште ослабленъ жилами. носимъ четꙑрьми.

wscp — West-Saxon Gospels [ang]   license: nc
  urn:nabu:proiel:wscp:102359
    & hi comon anne laman to him berende, þone feower men bæron.

… (Armenian, SBLGNT, the WEB English, Clementine Vulgate, and the four CCMH OCS witnesses trimmed)

Search by dictionary form. bin/nabu search --lemma λέγω finds every inflected attestation over the gold treebank annotations — λέγουσι, λέγοιεν, and the suppletive εἶπας/εἰπεῖν that no surface-string query can reach. Diacritics are optional on the query.

Open the dictionary. bin/nabu define λόγος prints the whole LSJ entry, with its citations resolved to passages in your own catalog where the corpus holds them (nabu show <urn> opens the cited line); bin/nabu define virtus does the same in Lewis & Short.

5. Connect your AI tools

The repository ships .mcp.json, so opening the directory in Claude Code registers the read-only MCP server automatically — the assistant can search, read, align, and define against everything you have synced, every passage carrying its license class, while remaining structurally unable to write to the library. Registration recipes for Claude Desktop and other clients, the tool reference, and the quoting etiquette are in docs/mcp.md.

Grow the library

Each further shelf is one nabu enable <source> (or enable <axis> for a whole desk) followed by its sync; bin/nabu sync --all re-syncs every enabled live-policy source in one pass. The full menu is config/sources.yml; real on-disk sizes for the larger shelves, measured 7 November 2026:

What each shelf is good for is surveyed on The Library; every text keeps its upstream license, recorded per document — the classes and per-source terms are on Sources. The non-commercial shelves are for research use and are never redistributed by the tooling.

The same walkthrough, kept in the repository alongside the code, is docs/quickstart.md.

Your desk

The starter shelf is running; the natural next move is to find the desk for your own field. bin/nabu list --axis prints the shelf census grouped under the 30 research desks — scholarly hats over the same sources, from the Classicist to the Assyriologist. Pick the one that fits and sync its members in a single command — bin/nabu sync celtic, or whichever desk is yours — then open its page: each desk carries its own member shelves, CLI recipes, search modes, and terminal setup for its scripts.

bin/nabu list --axis        # the shelf census, grouped by research desk
bin/nabu axis celtic        # one desk's card: members, holdings, gold coverage
bin/nabu sync celtic        # sync that desk's enabled members