ndi-cli

ndi — the NDI platform CLI. Document operations, jobs, and workspace lifecycle wrap the same /v1 methods as ndi-sdk. ask-file also runs inside an agent sandbox, next to the file commands only an agent run has; every other verb is refused there.

Setup

ndi login                                          # browser device-code; writes ~/.ndi/config.toml
export NDI_BASE_URL="https://ndi-api.nace.ai"      # optional; default shown
export NDI_WORKSPACE_ID="<workspace uuid>"         # or: ndi workspace use <id>

$NDI_API_KEY still wins over the file. $NDI_CONFIG_PATH overrides the config location. Workspace-scoped verbs also take --workspace ID.

Commands

Sources

SOURCE for document ops:

• local file — uploaded, then the handle is used
• directory — supported files, one job each (-j N, default 4)
• https://... — fetched by the server
• ndi://upload/<uuid> — a prior ndi upload
• jobid://<uuid> or a bare UUID — reuse a parse job (not classify)
• ws://<file_id> — a workspace file (needs a workspace)
• - — a jobid:// / UUID line, or raw bytes with --file-name

ndi parse a.pdf -o id | ndi extract - -s schema.json
ndi files upload ./corpus --ingest
ndi ledger-understanding start          # --force to re-scan; --selection-id after confirm
ndi ledger-understanding get
ndi ledger-understanding sources --review-reading-id READING
ndi ledger-understanding select --primary SRC --supporting SRC --revision REV

ndi files upload DIR keeps relative paths under --path (default: the directory name) and uploads in parallel (-j, default 8). Unsupported files (and .DS_Store) are skipped; a warning on stderr lists them when the run finishes. --ingest then queues ingestion in batches of 1000 file ids. A single file still requires --path.

Output

Result content goes to stdout; status (job <id> queued, saved …) goes to stderr. -o auto|md|json|payload|id picks the shape. --json is an alias for -o json.

The default (auto) prints the full JSON response. When that is over $NDI_OUTPUT_LIMIT characters (default 40,000), the compact text rendering prints instead and stderr carries note: output shortened … with the full size. --json always prints it whole, and --save / --out-dir always write it whole. Commands whose output is the content itself (ws context, parse markdown) print it as before. --save PATH / --out-dir DIR write files. --async submits and prints the job id.

When a Parse result has external complete content, -o auto and -o md print the inline preview. Use -o json or -o payload to inspect its disclosure and authenticated full-content URL. A final-size preview carries content_truncated; reduced-layout Office parsing carries parse_fidelity. Documents use document.content_url; workbooks use the affected document.spreadsheet.sheets[].content_url. The CLI does not download these URLs automatically.

API failures exit 1. Usage / config errors exit 2. Schema-validation failures also show up to five field constraints, each limited to 500 characters; request input and unrelated error-detail fields are omitted. Unsupported inputs print error: 422 [unsupported_file_type] ... to stderr and exit 1. ndi upload prints no handle, document operations print no job ID, and ndi files upload --ingest creates no workspace file or ingestion job. The server checks a bounded byte prefix, rejects conclusive filename/content conflicts, and treats the multipart Content-Type as advisory.

See the CLI guide for the full command reference. SKILL.md is the agent-facing guide to reading a workspace with ndi.