Metadata-Version: 2.4
Name: ndi-cli
Version: 0.11.0
Summary: NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools
Keywords: ndi,cli,document-intelligence,coding-agents
Author: Nace AI
Author-email: Nace AI <engineering@nace.ai>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: ndi-sdk>=0.26,<1
Requires-Dist: truststore>=0.10.4,<1
Requires-Python: >=3.11
Project-URL: Homepage, https://ndi-api.nace.ai
Description-Content-Type: text/markdown

# ndi-cli

`ndi` — the NDI platform CLI. Document operations, jobs, and workspace
lifecycle wrap the same `/v1` methods as `ndi-sdk`. The six workspace tools
also run inside an agent sandbox; every other verb is refused there.

## Setup

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

| Command | Use |
|---|---|
| `ndi login` | Authorize and save the API key |
| `ndi version` | CLI + SDK versions |
| `ndi upload FILE` | Stage bytes; prints `ndi://upload/<id>` |
| `ndi parse SOURCE` | Markdown / text / blocks |
| `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
| `ndi split SOURCE --class id:label` | Logical sections |
| `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (standalone quotes only; after search, poll `grounding_job_ids`) |
| `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
| `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
| `ndi files upload\|list\|get\|delete` | Workspace files (a directory walks nested files; `--ingest` then queues ingestion) |
| `ndi ingest` | Queue ingestion |
| `ndi automatic-search QUERY` | Service chooses fact, deep, or filtered search; prints the route and the output job id |
| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search; then `ndi job` on each printed `grounding_job_ids` entry |
| `ndi filtered-search QUERY` | Corpus filter/rank/count over the metadata catalog (`--cursor` pages an earlier run) |
| `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--reasoning-effort` for the thinking budget) |
| `ndi ledger-understanding start\|get\|sources\|select\|selection` | Measure the ledger package, confirm sources, or read the latest report |
| `ndi folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |

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

```bash
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`. `--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](https://docs.ndi.nace.ai/guides/cli) for the full command
reference. `SKILL.md` is the agent-facing guide to the six workspace tools.
