nace-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{nace_cli-0.1.0 → nace_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nace-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Nace CLI: calibrated decisions and document jobs from the shell
 Keywords: drex,nace,cli,document-intelligence
 Author: Nace AI
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Dist: nace-sdk>=0.1,<1
+Requires-Dist: nace-sdk>=0.2,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://console.nace.ai
@@ -83,7 +83,7 @@ nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use uploa
 nace upload-session --path big.csv --total-size-bytes 734003200
 ```
 
-`upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
+`nace upload DIR` uploads every file under a folder, keeping its path inside the folder under `--path` (default: the folder's name), `-j` at a time (default 8). Hidden files and folders are left out, and a file the document service refuses as `unsupported_file_type` is skipped: stderr lists them when the run ends. `--ingest` (with `--workspace`) then ingests what was uploaded, 1000 files per ingestion. `upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
 
 ## Jobs and their files
 
@@ -111,13 +111,29 @@ nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for t
 nace schema-version sch_... 1
 ```
 
+## Workspaces and search
+
+```bash
+nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+nace workspace-use <workspace_id>          # later commands use it; --workspace ID or $NACE_WORKSPACE_ID win
+nace upload ./report.pdf --workspace <workspace_id> --path reports/2025/report.pdf
+nace upload ./fy25 --workspace <workspace_id> --ingest   # every file under a folder, 8 at a time, then ingested
+nace ingest --path-prefix reports/         # makes the files searchable
+nace workspace-files --status failed
+nace search "What were total liabilities at year end?"
+nace qa "What was total freight spend in FY2024?"   # stderr: session <id>; follow up with --session
+nace kg-build
+```
+
+`search` and `qa` print the answer as the ndi CLI did: the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
+
 ## Output and exit codes
 
-Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. Exit `0` on success, `1` on an API or job failure (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
+Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
 
-Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create` and `schema-version-add` are never retried.
+Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create`, `schema-version-add` and `workspace-create` are never retried.
 
-Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 
 ## License
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/README.md

@@ -58,7 +58,7 @@ nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use uploa
 nace upload-session --path big.csv --total-size-bytes 734003200
 ```
 
-`upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
+`nace upload DIR` uploads every file under a folder, keeping its path inside the folder under `--path` (default: the folder's name), `-j` at a time (default 8). Hidden files and folders are left out, and a file the document service refuses as `unsupported_file_type` is skipped: stderr lists them when the run ends. `--ingest` (with `--workspace`) then ingests what was uploaded, 1000 files per ingestion. `upload-grant` and `upload-session` print JSON for another client to upload with: the CLI doesn't send parts or complete a session itself, and `nace upload` (or a local-file `SOURCE`) does every step for you.
 
 ## Jobs and their files
 
@@ -86,13 +86,29 @@ nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for t
 nace schema-version sch_... 1
 ```
 
+## Workspaces and search
+
+```bash
+nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+nace workspace-use <workspace_id>          # later commands use it; --workspace ID or $NACE_WORKSPACE_ID win
+nace upload ./report.pdf --workspace <workspace_id> --path reports/2025/report.pdf
+nace upload ./fy25 --workspace <workspace_id> --ingest   # every file under a folder, 8 at a time, then ingested
+nace ingest --path-prefix reports/         # makes the files searchable
+nace workspace-files --status failed
+nace search "What were total liabilities at year end?"
+nace qa "What was total freight spend in FY2024?"   # stderr: session <id>; follow up with --session
+nace kg-build
+```
+
+`search` and `qa` print the answer as the ndi CLI did: the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
+
 ## Output and exit codes
 
-Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. Exit `0` on success, `1` on an API or job failure (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
+Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
 
-Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create` and `schema-version-add` are never retried.
+Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, but only while the retry can start within 30 s of the first attempt, so a request that fails after 30 s, such as one that hit `--timeout` (120 s) or a slow `529`, is not retried. `schema-create`, `schema-version-add` and `workspace-create` are never retried.
 
-Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 
 ## License
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Nace CLI: calibrated decisions and document jobs from the shell"
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "nace-sdk>=0.1,<1",
+    "nace-sdk>=0.2,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Nace CLI: calibrated decisions and document jobs from the shell"
 authors = [
     { name = "Nace AI", email = "engineering@nace.ai" }
@@ -27,7 +27,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "nace-sdk>=0.1,<1",
+    "nace-sdk>=0.2,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/src/nace_cli/__init__.py

@@ -6,4 +6,4 @@ over ``nace-sdk``. Credentials come from
 ``$NACE_API_KEY`` / ``$NACE_BASE_URL`` or ``~/.nace/config.toml``.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{nace_cli-0.1.0 → nace_cli-0.2.0}/src/nace_cli/_cli.py

@@ -16,7 +16,8 @@ from nace_sdk import NaceAPIConnectionError, NaceAPIError, NaceClient, NaceError
 from nace_sdk.constants import LOG_LEVEL_ENV, read_env
 from nace_sdk.credentials import CredentialsError, resolve_credentials
 
-from nace_cli import _decide, _docops, _jobs, _login, _schemas
+from nace_cli import _decide, _docops, _jobs, _login, _schemas, _search, _upload, _workspaces
+from nace_cli._inputs import check_one_stdin_flag
 from nace_cli._output import CommandFailed
 
 #: Long enough for a decision (Drex holds one up to 60 s) and for a document
@@ -46,6 +47,7 @@ def main(argv: list[str] | None = None) -> int:
         return 2
     _log_to_stderr()
     try:
+        check_one_stdin_flag(args)
         if args.family == "standalone":
             return args.run(args)
         credentials = resolve_credentials()
@@ -93,6 +95,15 @@ def _validation_lines(exc: NaceAPIError) -> list[dict[str, Any]]:
     return lines
 
 
+#: What to do next for the workspace and search errors, by code.
+_WORKSPACE_HINTS = {
+    "workspace_not_found": "`nace workspaces` lists the workspaces your key can use; `nace workspace-use ID` saves one.",
+    "session_busy": "The conversation's last turn is still running: wait for it with `nace job <id> --wait`, then ask again.",
+    "rate_limited": "Automatic searches and QA turns share a limit of 60 per account every 10 minutes.",
+    "access_denied": "Your key can use the workspace but not do this: ask an account owner or admin, or whoever created the workspace.",
+}
+
+
 def report_status_error(exc: NaceAPIError) -> None:
     """One line a person can act on, plus where a request failed validation."""
     label = "/".join(str(part) for part in (exc.type, exc.code) if part)
@@ -112,6 +123,16 @@ def report_status_error(exc: NaceAPIError) -> None:
             print(f"  Pay the unpaid invoice at {billing}", file=sys.stderr)
         else:
             print(f"  Top up or add a card at {billing}", file=sys.stderr)
+    # An older nace-sdk (>=0.1) has no `idempotency_key` on its errors.
+    resume_key = getattr(exc, "idempotency_key", None)
+    if exc.code == "job_pending" and resume_key:
+        # The job may have started and be billed; the same key and body resume it instead of creating another.
+        print(f"  The job may still be running. Rerun the same command with --idempotency-key {resume_key} to resume it.", file=sys.stderr)
+    hint = _WORKSPACE_HINTS.get(exc.code or "")
+    if hint:
+        print(f"  {hint}", file=sys.stderr)
+    if exc.code == "rate_limited" and (wait := exc.headers.get("retry-after")):
+        print(f"  Run it again in {wait}s.", file=sys.stderr)
     if exc.code == "path_conflict":
         print(
             "  Upload to another path (--upload-path, or --path on `nace upload`), or pass --on-conflict new_version to add a version of that file.",
@@ -123,7 +144,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="nace",
         description=(
-            "Nace CLI: calibrated decisions and document jobs. Credentials come from "
+            "Nace CLI: calibrated decisions, document jobs, workspaces and search. Credentials come from "
             "$NACE_API_KEY / $NACE_BASE_URL or ~/.nace/config.toml (`nace login`). "
             "Set $NACE_LOG_LEVEL=debug to log each request to stderr."
         ),
@@ -141,9 +162,12 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command")
     _login.add_parsers(sub)
     _decide.add_parsers(sub, common)
+    _upload.add_parsers(sub, common)
     _docops.add_parsers(sub, common)
     _jobs.add_parsers(sub, common)
     _schemas.add_parsers(sub, common)
+    _workspaces.add_parsers(sub, common)
+    _search.add_parsers(sub, common)
     return parser
 
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/src/nace_cli/_decide.py

@@ -3,14 +3,27 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import sys
+from pathlib import Path
 from typing import Any
 
-from nace_sdk import Choice, ChoiceAnswer, ListModelsResponse, NaceClient, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse
+from nace_sdk import Choice, ChoiceAnswer, ListModelsResponse, NaceClient, Noul, NoulAnswer, Score, ScoreAnswer, SystemOneResponse, image_input
+from nace_sdk.images import _media_type
 
+from nace_cli._docops import parse_ws_source, upload_file, workspace_source
 from nace_cli._inputs import read_json, read_text
 from nace_cli._output import to_json
 
+#: The only model that reads images, and the one `--image` picks when no model is named.
+IMAGE_MODEL = "drex-max"
+#: Drex Max reads at most this many images per request.
+MAX_IMAGES = 8
+#: Local images up to this size are sent inline; larger ones are uploaded first (8 inline fit the 4 MiB body).
+INLINE_IMAGE_BYTES = 256 * 1024
+#: Where `--image` uploads larger images, named by their content.
+IMAGE_UPLOAD_FOLDER = "drex-max-images"
+
 
 def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
     decide = sub.add_parser(
@@ -31,6 +44,18 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     decide.add_argument("--score", action="append", default=[], metavar="NAME=LOW,...,HIGH[: INSTRUCTIONS]", help="Ordered levels.")
     decide.add_argument("--questions", default=None, metavar="JSON", help="Questions object: inline JSON, @FILE or a path.")
     decide.add_argument("--body", default=None, metavar="JSON", help="A whole request body; other flags override its fields.")
+    decide.add_argument(
+        "--image",
+        dest="images",
+        action="append",
+        default=[],
+        metavar="IMAGE",
+        help=(
+            f"An image for Drex Max (PNG, JPEG or WebP); repeatable, up to {MAX_IMAGES}, read in order as Image 1, Image 2... "
+            f"A local file up to {INLINE_IMAGE_BYTES // 1024} KiB is sent inline; a larger one is uploaded first. "
+            f"Sets --model {IMAGE_MODEL} unless you name one."
+        ),
+    )
     decide.add_argument("-m", "--model", default=None, help="Model id (default drex-latest). See `nace models`.")
     decide.set_defaults(run=run_decide, family="client")
 
@@ -66,10 +91,52 @@ def build_request(args: argparse.Namespace) -> dict[str, Any]:
         raise ValueError("--state is required (text, @FILE, or - for stdin)")
     if args.model:
         body["model"] = args.model
+    elif args.images and "model" not in body:
+        body["model"] = IMAGE_MODEL
+    if len(args.images) > MAX_IMAGES:
+        raise ValueError(f"at most {MAX_IMAGES} --image per request, got {len(args.images)}")
+    for spec in args.images:
+        _check_image(spec)
     body["questions"] = questions
     return body
 
 
+def _check_image(spec: str) -> None:
+    """Refuse a bad ``--image`` before anything is uploaded or sent."""
+    if spec.startswith("ws:"):
+        parse_ws_source(spec)
+        return
+    path = Path(spec)
+    if not path.is_file():
+        raise ValueError(f"--image: no such file, and not ws:<workspace>/<file>: {spec}")
+    with path.open("rb") as handle:
+        head = handle.read(12)
+    if _media_type(head) is None:
+        raise ValueError(f"--image: {spec} is not a PNG, JPEG or WebP image")
+
+
+def resolve_images(client: NaceClient, specs: list[str]) -> list[Any]:
+    """Each ``--image`` as an ``images`` entry: ws: as a file reference, a small file inline, a larger one uploaded."""
+    images: list[Any] = []
+    for spec in specs:
+        if spec.startswith("ws:"):
+            workspace_id, file_id = parse_ws_source(spec)
+            images.append({"type": "workspace_file", "workspace_id": workspace_id, "file_id": file_id})
+            continue
+        path = Path(spec)
+        data = path.read_bytes()
+        if len(data) <= INLINE_IMAGE_BYTES:
+            images.append(image_input(data))
+            continue
+        # Named by content, so the same image again returns the file already there.
+        target = f"{IMAGE_UPLOAD_FOLDER}/{hashlib.sha256(data).hexdigest()[:16]}{path.suffix.lower()}"
+        print(f"uploading {path.name}", file=sys.stderr)
+        uploaded = upload_file(client, path, path=target, on_conflict=None)
+        print(f"uploaded {workspace_source(uploaded)}", file=sys.stderr)
+        images.append(image_input(uploaded))
+    return images
+
+
 def _state(text: str) -> Any:
     """A state that parses as a JSON object or array is sent as JSON; anything else as text."""
     stripped = text.strip()
@@ -99,14 +166,17 @@ def _labelled(spec: str, flag: str) -> tuple[str, list[str], str | None]:
 
 def run_decide(client: NaceClient, args: argparse.Namespace) -> int:
     body = build_request(args)
-    extra = {key: value for key, value in body.items() if key not in ("state", "questions", "model")}
-    response = client.system_one(body["state"], body["questions"], model=body.get("model"), extra_body=extra or None)
+    if args.images:
+        body["images"] = resolve_images(client, args.images)
+    extra = {key: value for key, value in body.items() if key not in ("state", "questions", "model", "images")}
+    response = client.system_one(body["state"], body["questions"], model=body.get("model"), images=body.get("images"), extra_body=extra or None)
     if args.json:
         print(response_json(response))
         return 0
     print(render_answers(response))
     timing = f" · {response.evaluation_time_ms:.0f} ms" if response.evaluation_time_ms is not None else ""
-    print(f"{response.model} · {response.usage.input_tokens} input tokens{timing} · {response.request_id}", file=sys.stderr)
+    image_tokens = f" ({response.usage.image_tokens} image)" if response.usage.image_tokens else ""
+    print(f"{response.model} · {response.usage.input_tokens} input tokens{image_tokens}{timing} · {response.request_id}", file=sys.stderr)
     return 0
 
 

{nace_cli-0.1.0 → nace_cli-0.2.0}/src/nace_cli/_docops.py

@@ -33,37 +33,40 @@ SOURCE_HELP = """\
 SOURCE is one of:
   https://...                   a public link the document service downloads
                                 (--file-name names the file when the link doesn't end in one)
-  a local file                  uploaded into your workspace first, then used as a workspace file
-  ws:<workspace_id>/<file_id>   a file already in your workspace (what `nace upload` prints)
+  a local file                  uploaded to the server first, then used from there
+  ws:<workspace_id>/<file_id>   a file already uploaded (what `nace upload` prints)
   job:<job_id>                  a finished parse job's result, so it is not parsed again
                                 (not for classify)
 """
 
 ON_CONFLICT_CHOICES = ("reject", "new_version")
+#: The most locations Ground returns per target.
+MAX_MATCHES = 50
 
 
 def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
-    upload = sub.add_parser("upload", parents=[common], help="Upload a file into your workspace; prints its ws: source.")
-    upload.add_argument("file", help="Local file.")
-    upload.add_argument("--path", default=None, help="Path in the workspace (default: the file name).")
-    _add_on_conflict(upload)
-    upload.set_defaults(run=run_upload, family="client")
-
+    # `nace upload` itself is in _upload, which registers it just before these.
     grant = sub.add_parser("upload-grant", parents=[common], help="Mint a one-use token another client can upload one file with.")
     grant.add_argument("--path", default=None, help="Pin the workspace path the upload must use.")
     grant.add_argument("--max-bytes", type=int, default=None, metavar="N", help="Largest file the grant accepts.")
     grant.add_argument("--total-size-bytes", type=int, default=None, metavar="N", help="Exact size the file must have.")
     grant.add_argument("--ttl-seconds", type=int, default=None, metavar="N", help="How long the grant stays valid.")
+    add_upload_workspace(grant, "The workspace the upload goes into")
     grant.set_defaults(run=run_upload_grant, family="client")
 
     session = sub.add_parser("upload-session", parents=[common], help="Open a resumable upload in parts for a large file.")
     session.add_argument("--path", required=True, help="Path of the file in the workspace.")
     session.add_argument("--total-size-bytes", type=int, required=True, metavar="N", help="The file's exact size.")
     session.add_argument("--ttl-seconds", type=int, default=None, metavar="N", help="How long the session accepts parts.")
-    _add_on_conflict(session)
+    add_on_conflict(session)
     session.add_argument("--idempotency-key", default=None, metavar="KEY", help="Retry-safe key; the same key returns the same session.")
+    add_upload_workspace(session, "The workspace the file goes into")
     session.set_defaults(run=run_upload_session, family="client")
 
+    delete = sub.add_parser("upload-delete", parents=[common], help="Delete an uploaded file and everything derived from it.")
+    delete.add_argument("workspace_file", metavar="ws:<workspace_id>/<file_id>", help="The file, as `nace upload` printed it.")
+    delete.set_defaults(run=run_upload_delete, family="client")
+
     parse = _operation(sub, common, "parse", "Convert a document to Markdown, text or layout blocks.")
     parse.add_argument(
         "--format",
@@ -71,6 +74,19 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
         default=None,
         help="Comma list of markdown,text,blocks (default: the API's markdown,blocks; stdout shows the Markdown).",
     )
+    parse.add_argument(
+        "--table-format", choices=("html", "markdown"), default=None, help="How tables are written in the Markdown and text (default html)."
+    )
+    parse.add_argument(
+        "--chunk", choices=("none", "page", "section"), default=None, help="Split the document into chunks for retrieval (default none)."
+    )
+    parse.add_argument(
+        "--figures",
+        choices=("omit", "include", "describe"),
+        default=None,
+        help="Drop figures, keep them, or keep and caption them (default include).",
+    )
+    parse.add_argument("--sheets", default=None, metavar="NAMES", help="A workbook's sheets to parse, a comma list of names (default: every sheet).")
     parse.add_argument(
         "--password",
         default=None,
@@ -81,11 +97,21 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
 
     split = _operation(sub, common, "split", "Split a multi-document file into the documents it contains.")
     _add_class_args(split)
+    split.add_argument(
+        "--unknown",
+        choices=("include", "force", "error"),
+        default=None,
+        help="Pages no class matches: keep them unclassified, give them the best class, or fail (default include).",
+    )
+    split.add_argument("--include-content", action="store_true", help="Give each segment its Markdown.")
     split.set_defaults(run=run_split)
 
     classify = _operation(sub, common, "classify", "Classify a document, or each page, into your classes.")
     _add_class_args(classify)
     classify.add_argument("--granularity", choices=("document", "page"), default=None, help="One label for the file, or one per page.")
+    classify.add_argument(
+        "--unknown", choices=("allow", "force_best"), default=None, help="Allow an unknown label, or force the closest class (default allow)."
+    )
     classify.set_defaults(run=run_classify)
 
     extract = _operation(sub, common, "extract", "Extract structured fields with a JSON Schema, inline or saved.")
@@ -94,11 +120,14 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     schema.add_argument("--schema-id", default=None, metavar="ID", help="A saved schema (sch_...), at its latest version.")
     extract.add_argument("--schema-version", type=int, default=None, metavar="N", help="With --schema-id, pin this version.")
     extract.add_argument("--instructions", default=None, help="Extra guidance for the extraction.")
+    extract.add_argument("--no-citations", action="store_true", help="Don't say where each field was read (citations.enabled false).")
     extract.set_defaults(run=run_extract)
 
     ground = _operation(sub, common, "ground", "Find where each target text appears in a document.", pages=False)
     ground.add_argument("--target", action="append", dest="targets", default=[], metavar="[ID=]TEXT", help="Repeatable; ids default to t1, t2, ...")
     ground.add_argument("--targets", dest="targets_file", default=None, metavar="JSON", help="JSON array of targets.")
+    ground.add_argument("--max-matches", type=int, default=None, metavar="N", help=f"Locations per target, 1 to {MAX_MATCHES} (default 10).")
+    ground.add_argument("--previews", action="store_true", help="Link a cropped image of each visual hit.")
     ground.add_argument(
         "--semantic",
         action="store_true",
@@ -107,7 +136,18 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     ground.set_defaults(run=run_ground)
 
 
-def _add_on_conflict(parser: argparse.ArgumentParser) -> None:
+def add_upload_workspace(parser: argparse.ArgumentParser, what: str) -> None:
+    # Only the flag: an upload without it goes to the server, whatever
+    # $NACE_WORKSPACE_ID or `nace workspace-use` say, as uploads did before workspaces.
+    parser.add_argument(
+        "--workspace",
+        default=None,
+        metavar="ID",
+        help=f"{what}. Without it, the file is uploaded to the server; $NACE_WORKSPACE_ID and `nace workspace-use` don't apply.",
+    )
+
+
+def add_on_conflict(parser: argparse.ArgumentParser) -> None:
     # Unset means the document service's reject, for a local SOURCE too: a job reads its workspace file's
     # current version when it starts, not when it is created, so new_version changes the input of jobs
     # still queued on that file.
@@ -129,7 +169,7 @@ def _operation(sub: argparse._SubParsersAction, common: argparse.ArgumentParser,
     parser.add_argument("source", help="https:// URL, local file, ws:<workspace>/<file>, or job:<parse job id>.")
     parser.add_argument("--file-name", default=None, metavar="NAME", help="For an https:// SOURCE: the file's name; its extension picks the parser.")
     parser.add_argument("--upload-path", default=None, metavar="PATH", help="For a local SOURCE: its path in the workspace (default: its name).")
-    _add_on_conflict(parser)
+    add_on_conflict(parser)
     if pages:
         # Ground reads whole documents: it has no page selection.
         parser.add_argument("-p", "--pages", default=None, metavar="SPEC", help="1-based pages, e.g. 3 or 1-5,8 (not with a job: SOURCE).")
@@ -205,10 +245,8 @@ def resolve_source(client: NaceClient, args: argparse.Namespace) -> Source:
     if spec.startswith("job:"):
         return ParseResultSource(job_id=_uuid(spec[4:], spec))
     if spec.startswith("ws:"):
-        workspace_id, sep, file_id = spec[3:].partition("/")
-        if not sep:
-            raise ValueError(f"expected ws:<workspace_id>/<file_id>, got {spec!r}")
-        return WorkspaceFileSource(workspace_id=_uuid(workspace_id, spec), file_id=_uuid(file_id, spec))
+        workspace_id, file_id = parse_ws_source(spec)
+        return WorkspaceFileSource(workspace_id=workspace_id, file_id=file_id)
     path = Path(spec)
     if not path.is_file():
         raise ValueError(f"no such file, and not a URL, ws: or job: source: {spec}")
@@ -218,9 +256,17 @@ def resolve_source(client: NaceClient, args: argparse.Namespace) -> Source:
     return uploaded.as_source()
 
 
-def upload_file(client: NaceClient, file: Path, *, path: str | None, on_conflict: OnConflict | None) -> UploadedFile:
+def parse_ws_source(spec: str) -> tuple[str, str]:
+    """``ws:<workspace_id>/<file_id>`` as its two ids, refused as a usage error unless both are ids."""
+    workspace_id, sep, file_id = spec.removeprefix("ws:").partition("/")
+    if not spec.startswith("ws:") or not sep:
+        raise ValueError(f"expected ws:<workspace_id>/<file_id>, got {spec!r}")
+    return _uuid(workspace_id, spec), _uuid(file_id, spec)
+
+
+def upload_file(client: NaceClient, file: Path, *, path: str | None, on_conflict: OnConflict | None, workspace_id: str | None = None) -> UploadedFile:
     try:
-        return client.documents.upload(file, path=path, on_conflict=on_conflict)
+        return client.documents.upload(file, path=path, on_conflict=on_conflict, workspace_id=workspace_id)
     except NaceAPIError:
         raise
     except NaceError as exc:
@@ -256,6 +302,17 @@ def _body(args: argparse.Namespace) -> dict[str, Any]:
     return body
 
 
+def _set(body: dict[str, Any], key: str, value: Any) -> None:
+    """Set a dotted request field from its typed flag, over whatever ``--options``/``--option`` gave, keeping the block's other fields."""
+    *parents, leaf = key.split(".")
+    target = body
+    for part in parents:
+        child = target.get(part)
+        target[part] = child = dict(child) if isinstance(child, dict) else {}
+        target = child
+    target[leaf] = value
+
+
 def _take(body: dict[str, Any], key: str, flag: Any, kind: type) -> Any:
     """A value the SDK takes as an argument: the flag's, else the body field's (which is removed either way)."""
     value = body.pop(key, None)
@@ -308,21 +365,30 @@ def _submit(client: NaceClient, args: argparse.Namespace, body: dict[str, Any],
     return submit_and_report(client, job, args)
 
 
-def run_upload(client: NaceClient, args: argparse.Namespace) -> int:
-    path = Path(args.file)
-    if not path.is_file():
-        raise ValueError(f"no such file: {args.file}")
-    uploaded = upload_file(client, path, path=args.path, on_conflict=args.on_conflict)
+def run_upload_delete(client: NaceClient, args: argparse.Namespace) -> int:
+    spec = args.workspace_file
+    if not spec.startswith("ws:"):
+        raise ValueError(f"expected ws:<workspace_id>/<file_id>, got {spec!r}")
+    workspace_id, sep, file_id = spec[3:].partition("/")
+    if not sep:
+        raise ValueError(f"expected ws:<workspace_id>/<file_id>, got {spec!r}")
+    deletion = client.documents.delete_file(_uuid(workspace_id, spec), _uuid(file_id, spec))
     if args.json:
-        print(uploaded.model_dump_json(indent=2, exclude_none=True))
+        print(deletion.model_dump_json(indent=2))
+    if deletion.status == "deleted":
+        print(f"deleted {spec}", file=sys.stderr)
     else:
-        print(workspace_source(uploaded))
+        print(f"still deleting {spec}: run the command again to check", file=sys.stderr)
     return 0
 
 
 def run_upload_grant(client: NaceClient, args: argparse.Namespace) -> int:
     grant = client.documents.create_upload_grant(
-        path=args.path, max_bytes=args.max_bytes, total_size_bytes=args.total_size_bytes, ttl_seconds=args.ttl_seconds
+        path=args.path,
+        max_bytes=args.max_bytes,
+        total_size_bytes=args.total_size_bytes,
+        ttl_seconds=args.ttl_seconds,
+        workspace_id=args.workspace,
     )
     print(grant.model_dump_json(indent=2))
     print("the token uploads one file into your workspace: hand it only to whoever uploads that file", file=sys.stderr)
@@ -335,6 +401,7 @@ def run_upload_session(client: NaceClient, args: argparse.Namespace) -> int:
         total_size_bytes=args.total_size_bytes,
         ttl_seconds=args.ttl_seconds,
         on_conflict=args.on_conflict,
+        workspace_id=args.workspace,
         idempotency_key=args.idempotency_key,
     )
     print(to_json(session.model_dump(mode="json")))
@@ -348,6 +415,14 @@ def run_parse(client: NaceClient, args: argparse.Namespace) -> int:
         output = body.get("output")
         formats = [item.strip() for item in args.formats.split(",") if item.strip()]
         body["output"] = {**(output if isinstance(output, dict) else {}), "formats": formats}
+    for key, value in (("output.table_format", args.table_format), ("chunking.strategy", args.chunk), ("figures.mode", args.figures)):
+        if value is not None:
+            _set(body, key, value)
+    if args.sheets is not None:
+        sheets = [name.strip() for name in args.sheets.split(",") if name.strip()]
+        if not sheets:
+            raise ValueError("--sheets takes a comma list of sheet names")
+        _set(body, "spreadsheet.sheets", sheets)
     if args.password is not None:
         body["password"] = read_secret(args.password, prompt="PDF password: ")
     return _submit(client, args, body)
@@ -355,6 +430,10 @@ def run_parse(client: NaceClient, args: argparse.Namespace) -> int:
 
 def run_split(client: NaceClient, args: argparse.Namespace) -> int:
     body = _body(args)
+    if args.unknown is not None:
+        body["unknown_policy"] = args.unknown
+    if args.include_content:
+        _set(body, "output.include_content", True)
     return _submit(client, args, body, classes=_classes(args, body))
 
 
@@ -362,6 +441,8 @@ def run_classify(client: NaceClient, args: argparse.Namespace) -> int:
     body = _body(args)
     if args.granularity:
         body["granularity"] = args.granularity
+    if args.unknown is not None:
+        body["unknown_policy"] = args.unknown
     return _submit(client, args, body, classes=_classes(args, body))
 
 
@@ -387,11 +468,19 @@ def run_extract(client: NaceClient, args: argparse.Namespace) -> int:
         if fields["schema_version"] is not None and fields["schema_id"] is None:
             raise ValueError("schema_version pins a version of a saved schema, so it needs schema_id")
     instructions = _take(body, "instructions", args.instructions, str)
+    if args.no_citations:
+        _set(body, "citations.enabled", False)
     return _submit(client, args, body, instructions=instructions, **fields)
 
 
 def run_ground(client: NaceClient, args: argparse.Namespace) -> int:
+    if args.max_matches is not None and not 1 <= args.max_matches <= MAX_MATCHES:
+        raise ValueError(f"--max-matches must be between 1 and {MAX_MATCHES}")
     body = _body(args)
+    if args.max_matches is not None:
+        _set(body, "options.max_matches", args.max_matches)
+    if args.previews:
+        _set(body, "options.include_previews", True)
     targets: list[Any] = []
     if args.targets_file:
         loaded = read_json(args.targets_file, what="--targets")