nora documents

Documents are the raw units of knowledge: files, pages, extracts. nora documents covers the full library CRUD surface: uploads (single file, large file, whole folder), external-URL registration, metadata patches (regulatory dates for time-aware retrieval), chunk inspection, tagging, supersede, and delete.

Command groups

Read: list, get, chunks, chunk-text, extracted-text
Ingest: upload, upload-large, upload-folder, create-external
Mutate: tag, update, supersede, delete
KG grafting: extract-structure

Read

`list`

nora documents list
nora documents list --tag billing

One row per document: id, title, content type, size, tags, last update. --tag narrows to one library folder. --json for scriptable output.

`get`

nora documents get doc_abc

Full metadata: title, source URL, content hash, tags, ingest pipeline, chunk count, supersede state.

`chunks`

# Full chunk rows
nora documents chunks doc_abc

# Short previews only
nora documents chunks doc_abc --preview --preview-len 300

# Paginate + search inside chunks
nora documents chunks doc_abc --limit 50 --offset 100 --q "coverage"

Lists a document’s persisted chunks. --preview caps at ~200 chars (or --preview-len <N>). --q runs a free-text filter inside chunk text.

`chunk-text`

nora documents chunk-text ch_xyz

Fetches one chunk’s full text, bypassing the preview cap.

`extracted-text`

nora documents extracted-text doc_abc

The document’s cached extracted text (OCR / PDF / text extractor output). Returns null when extraction hasn’t run yet.

Ingest

`upload`: inline

nora documents upload ./contract.pdf \
  --name "Q3 contract" \
  --mime application/pdf \
  --tags billing,current

Base64-inlines the file to the server. Cap: ~45 MB original / ~60 MB post-encoded. --mime optional (defaults to application/octet-stream). --name optional (defaults to the file’s basename). --tags stamps folder tags on the row.

`upload-large`: S3 presigned

nora documents upload-large ./scan.tif --tags scans

Asks the server for an S3 presigned PUT URL, then PUTs the bytes directly, with no base64 overhead. Requires the deployment to have NORA_S3_BUCKET configured (otherwise a clear error). Use this above ~45 MB.

`upload-folder`: batch

# Top level only (default)
nora documents upload-folder ./inbox

# Whole tree
nora documents upload-folder ./inbox --recursive

# Skip patterns + include hidden
nora documents upload-folder ./inbox --recursive \
  --exclude .DS_Store --exclude .tmp --hidden

# Force S3-presigned for every file
nora documents upload-folder ./inbox --presigned

Walks a folder and uploads every file. Auto-picks the transport per file: base64 inline under ~45 MB, S3-presigned above. --presigned forces the S3 path (useful when the tenant restricts inline payloads or the network prefers direct S3 PUT). Prints a progress line per file and a summary at the end. Idempotent per file: rerun to catch up after a mid-batch failure.

`create-external`: reference an URL

nora documents create-external \
  --url https://example.com/regulation.pdf \
  --name "Regulation X" \
  --mime application/pdf \
  --tags regulation,external

Registers an external URL as a document row (storage_kind='external'). Nora references the URL. It does not copy the bytes.

Mutate

`tag`

# Add
nora documents tag doc_abc --add customer-facing,billing

# Remove
nora documents tag doc_abc --remove deprecated

# Move between folders in one call
nora documents tag doc_abc --add current --remove draft

Tags are library folder membership. Comma-separated lists accepted. Both --add and --remove are optional (at least one required).

`update`: patch metadata

nora documents update doc_abc \
  --set-name "Q3 2026 policy v2" \
  --set-published-at 2026-08-01 \
  --set-effective-at 2026-09-01 \
  --set-effective-until 2027-09-01 \
  --set-issuer "Acme Insurance" \
  --set-revision "v2"

Tri-state per field: pass --set-<field> to set, --clear-<field> to null it, omit to leave alone. Fields:

--set-name / --clear-...
--set-published-at <YYYY-MM-DD>: publication date.
--set-effective-at <YYYY-MM-DD>: valid-from date (feeds G1 as_of retrieval).
--set-effective-until <YYYY-MM-DD>: valid-until (exclusive). Old contracts still match earlier as_of values; NULL / cleared = still current.
--set-issuer <text>: who issued the doc.
--set-revision <text>: version label.

The effective_at / effective_until pair is what makes time-aware retrieval work. Set them on regulated / dated documents so as_of queries land on the right version.

`supersede`

nora documents supersede doc_abc
# Restore
nora documents supersede doc_abc --restore

Marks the document as superseded: excluded from every search path but still queryable for audit. The version_misrank retrieval fix (loop-spec §F.2). --restore reverses it. Prefer supersede over delete: reversible, keeps the audit trail.

`delete`

nora documents delete doc_abc

Removes the document row and its chunks. S3 bytes are garbage-collected out-of-band. External-URL rows just drop the reference. Irreversible. Supersede is almost always what you want instead.

KG grafting

`extract-structure`

# Mint a fresh KG named after the doc
nora documents extract-structure doc_abc

# Graft into an existing KG instance
nora documents extract-structure doc_abc --kg-instance kg_regulation_map

# Pin a specific extraction model
nora documents extract-structure doc_abc --model gpt-5.4

Runs the LLM structure-extractor on the document, grafting hierarchical nodes / edges into a causal graph instance. Omit --kg-instance to mint a fresh KG named after the document.

Recipes

Bulk-ingest a Dropbox export

nora documents upload-folder ~/Downloads/dropbox-export \
  --recursive --exclude .DS_Store

Move a set of docs from one folder to another

for id in $(nora documents list --tag old-folder --json | jq -r '.[].id'); do
  nora documents tag $id --add new-folder --remove old-folder
done

Backfill regulatory dates on already-ingested policies

while read id date; do
  nora documents update $id --set-effective-at "$date"
done < policy-dates.tsv

policy-dates.tsv has doc_id<TAB>YYYY-MM-DD per line.

Snapshot document metadata to git

nora documents list --json > snapshots/documents-$(date +%Y%m%d).json

Tracks library changes without exporting content.

Audit tag coverage

nora documents list --json | jq -r '.[] | select((.tags // []) | length == 0) | .id'

Prints untagged documents: candidates for auto-tagging via a Foundry enricher.

Preview the first chunks of every doc in a folder

for id in $(nora documents list --tag billing --json | jq -r '.[].id'); do
  echo "=== $id ==="
  nora documents chunks $id --preview --limit 3
done

Where document IDs come from

App every library document shows its ID in the details panel.
Foundry logs pipelines logs get shows IDs of documents a run produced.
documents list for scripting.

CLI

SDK

Local App

nora documents

Command groups

Read

`list`

`get`

`chunks`

`chunk-text`

`extracted-text`

Ingest

`upload`: inline

`upload-large`: S3 presigned

`upload-folder`: batch

`create-external`: reference an URL

Mutate

`tag`

`update`: patch metadata

`supersede`

`delete`

KG grafting

`extract-structure`

Recipes

Bulk-ingest a Dropbox export

Move a set of docs from one folder to another

Backfill regulatory dates on already-ingested policies

Snapshot document metadata to git

Audit tag coverage

Preview the first chunks of every doc in a folder

Where document IDs come from

​Command groups

​Read

​list

​get

​chunks

​chunk-text

​extracted-text

​Ingest

​upload: inline

​upload-large: S3 presigned

​upload-folder: batch

​create-external: reference an URL

​Mutate

​tag

​update: patch metadata

​supersede

​delete

​KG grafting

​extract-structure

​Recipes

​Bulk-ingest a Dropbox export

​Move a set of docs from one folder to another

​Backfill regulatory dates on already-ingested policies

​Snapshot document metadata to git

​Audit tag coverage

​Preview the first chunks of every doc in a folder

​Where document IDs come from

Command groups

Read

`list`

`get`

`chunks`

`chunk-text`

`extracted-text`

Ingest

`upload`: inline

`upload-large`: S3 presigned

`upload-folder`: batch

`create-external`: reference an URL

Mutate

`tag`

`update`: patch metadata

`supersede`

`delete`

KG grafting

`extract-structure`

Recipes

Bulk-ingest a Dropbox export

Move a set of docs from one folder to another

Backfill regulatory dates on already-ingested policies

Snapshot document metadata to git

Audit tag coverage

Preview the first chunks of every doc in a folder

Where document IDs come from