The CLI

The entire library is available as a command-line tool — search, read, and download manuscript pages without leaving your terminal.

npx leonardo-davinci random --subject anatomy

Install

npm install -g leonardo-davinci

This installs the da-vinci command (the npm package is leonardo-davinci; the command matches this API’s name). One-off use via npx leonardo-davinci needs no install. Requires Node 18.17+.

Interactive mode

Run da-vinci with no command and the terminal becomes the studiolo — a red-chalk workspace with a prompt. Type commands without the da-vinci prefix (random, search flying machine, folio codex-atlanticus 1646 --full), clear to repaint, quit to leave. The session scrolls back like a conversation and stays in your terminal history after you quit. Scripts and pipes are unaffected: non-interactive invocations print plain output.

Find one page — never a guess

da-vinci find "odometer and pedometer"     # one page (exit 0)
da-vinci find CA 266v                      # a folio by its number; any collection name works
da-vinci find optics and birds             # several pages fit → a short list (exit 2)

find answers in exactly one of three ways, and the exit code says which: 0 one page (folio in the JSON; how says whether a label or a search decided it), 2 several pages fit (candidates), 4 nothing fits. A folio label names a page outright. A phrase is searched, and the best page is the answer only when it clearly leads — its score well ahead of the runner-up and every term found in one passage or the title. A thematic query like optics and birds is legitimately a list.

Commands

Command	What it does
`da-vinci find <phrase \| CA 266v>`	One page, or a short list — never a guess (`--collection`, `--subject`)
`da-vinci search <query…>`	Ranked search over titles, summaries, passages, the English translation and the Italian transcription; terms are AND-ed, aliases cross the languages (`--subject`, `--collection`, `--limit`, `--offset`)
`da-vinci folio <collection> <index \| label>`	Read one page — summary, passages, translation (`--full`, `--open`)
`da-vinci collections` · `collection <slug>`	The 28 collections and their pages
`da-vinci subjects` · `subject <id>`	The frozen 25-term vocabulary and the pages tagged with each
`da-vinci random`	A random page (`--subject`, `--collection`, `--open`)
`da-vinci pull <slug/page…>`	Save several scans at once: refs, `--from-search "<q>"`, or `--stdin`; `--text` saves each page’s texts as JSON beside the scan (`--size`, `--out`, `--overwrite`)
`da-vinci download <slug> <index>`	Save one scan (`--size thumbnail\|medium\|highRes`, `--out <dir>`, `--text`)
`da-vinci open <slug> [index]`	Open the page on venivididavinci.com

A collection may be given as its slug or any name people use — ca, atlanticus, arundel, "ms f", "forster iii", "madrid ii". A page may be its index in the collection (531) or the folio written on it (266v, 0266 v, 266 recto, 12r bis). Every command accepts --json for machine-readable output, --format md for a markdown table, --fields slug,index,url to trim a record, and --quiet for slug/index refs only — pipe them to jq, scripts, or agents:

da-vinci find "the caladrius" --json --fields slug,index,label,url
da-vinci search "flight of birds" --collection "ms f" --json | jq '.data[] | {slug, index, passage: .matchedItem.heading}'
da-vinci folio codex-atlanticus 1646 --json | jq -r '.folio.enrichment.english[].textEN'

Exit codes: 0 ok · 1 usage · 2 several pages fit (listed) · 3 network or rate limit · 4 none · 5 some pulls failed. Under --json, errors are { "ok": false, "error": { "code", "message" } } on stdout. Codes 2 and 4 are answers, not failures.

Examples

# A page of the day for your terminal startup
da-vinci random

# Everything Leonardo wrote about water, 20 pages at a time
da-vinci subject hydraulics --limit 20

# Read the famous flying-machine sheet in full
da-vinci folio codex-atlanticus 1646 --full

# The same sheet by its folio number
da-vinci folio ca 0844r

# Save the high-resolution scan of an Arundel opening, with its texts
da-vinci download codex-arundel 30 --size highRes --out ./scans --text

# Five pages on the centre of gravity, scans and texts
da-vinci pull --from-search "centre of gravity" --limit 5 --text --out ./cg

Rate limits & keys

The CLI uses the same rate limits as the API — anonymous 60/hour. Pass --api-key or set DAVINCI_API_KEY for higher tiers.

Security

Built to be maximally auditable: zero runtime dependencies (one file of Node builtins), no install scripts, no telemetry, HTTPS only to venivididavinci.com origins (downloads included), validated inputs, traversal-safe downloads. Ships exactly four files — verify with npm pack leonardo-davinci --dry-run.

Attribution

Content fetched through the CLI carries the same attribution terms as the API — every folio includes a ready-made attribution string.

Getting started

Concepts

Tools

Install

Interactive mode

Find one page — never a guess

Commands

Examples

Rate limits & keys

Security

Attribution

​Install

​Interactive mode

​Find one page — never a guess

​Commands

​Examples

​Rate limits & keys

​Security

​Attribution

Install

Interactive mode

Find one page — never a guess

Commands

Examples

Rate limits & keys

Security

Attribution