> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
# 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](/build/knowledge/tag) 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/build/knowledge/upload)) or a Foundry pipeline for automated ingest (see [`nora pipelines`](/cli/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.