nora documents

Manage documents in your knowledge library — list, tag, supersede.

Documents are the raw units of knowledge — files, pages, extracts. Once ingested (via Foundry pipeline or web upload), they live in your library where Agents can retrieve from them.

The documents CLI is the surface for the library’s day-to-day management: listing, tagging, and superseding.

Commands

Command	Description
documents list [--tag <tag>]	List documents (optionally in a folder tag).
documents get <doc-id>	Print full metadata for one document.
documents supersede <doc-id> [--restore]	Mark superseded (or restore).
documents tag <doc-id> [--add ...] [--remove ...]	Add or remove folder tags.

documents list

nora documents list
nora documents list --tag billing

Prints one row per document: ID, title, content type, size, tags, last update.

Add --json for scriptable output.

documents get

nora documents get doc_abc

Prints full metadata — title, source URL, content hash, tags, ingestion pipeline that produced it, chunk count, and supersede state.

documents supersede

nora documents supersede doc_abc
# Later, undo:
nora documents supersede doc_abc --restore

Marks the document as superseded — hidden from all retrieval but still queryable for audit. Superseded chunks stop matching queries within seconds.

--restore reverses supersede. The document rejoins the retrieval index.

Prefer supersede over delete: it’s reversible and preserves the audit trail. Delete is only appropriate for true takedowns (PII, legal removal) — and even then, use the library UI, not the CLI, because delete requires confirmation.

documents tag

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

# Remove
nora documents tag doc_abc --remove deprecated

# Both at once
nora documents tag doc_abc --add current --remove draft

Tags are the primary way you slice a large library. See Tag & organize for tag hygiene.

Comma-separated lists accepted. Both --add and --remove are optional (though at least one is required).

Recipes

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

Supersede everything older than a date

cutoff="2025-01-01"
for id in $(nora documents list --json | jq -r --arg cutoff "$cutoff" '.[] | select(.updated_at < $cutoff) | .id'); do
  nora documents supersede $id
done

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.

Snapshot document metadata to git

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

Useful for tracking library changes over time without exporting content.

What the CLI does NOT do

• Upload — use the app for one-off uploads (see Upload documents) or a Foundry pipeline for automated ingest (see nora pipelines).
• Delete — CLI can only supersede. To hard-delete, use the app UI (with double confirmation).
• Edit content — documents are immutable once ingested; edit the source and re-ingest.

These constraints are intentional — the CLI is optimized for scripted operations, not for edits that need visual review.

Where document IDs come from

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