nace-cli 0.1.0__py3-none-any.whl

nace_cli/_jobs.py

@@ -0,0 +1,292 @@
+"""``nace job``, ``jobs``, ``cancel``, ``file``, ``job-request``, ``rows``, ``events``, and the wait every create uses."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import itertools
+import sys
+from collections.abc import Iterator
+from typing import Any
+
+from nace_sdk import (
+    DOCUMENT_OPERATIONS,
+    JOB_STATUSES,
+    MAX_ROWS_PAGE_SIZE,
+    DocumentJob,
+    NaceAPIConnectionError,
+    NaceAPIError,
+    NaceClient,
+    NaceError,
+    NaceJobFailedError,
+    NaceJobTimeoutError,
+    RowsPage,
+)
+from nace_sdk._core.endpoints import MAX_PAGE_SIZE, job_path, resource_path
+from nace_sdk._core.jobs import DEFAULT_WAIT_SECONDS
+
+from nace_cli._inputs import job_id
+from nace_cli._output import add_job_output_args, emit, fetch_file, job_line, output_mode, render_job, to_json
+
+#: Extensions of the job files the document service always sends as one type (it writes figure
+#: and ground crops as PNG). Events, a stream, get none.
+_EXTENSIONS = {
+    "document-content": ".md",
+    "spreadsheet-content": ".md",
+    "parse-images": ".png",
+    "ground-crops": ".png",
+    "converted-pdf": ".pdf",
+    "parse-transcript": ".json",
+    "ground-transcript": ".json",
+    "spreadsheet-cell-maps": ".json",
+    "spreadsheet-rows": ".json",
+    "request": ".json",
+}
+
+
+def add_wait_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--async", dest="async_submit", action="store_true", help="Print the job id and return at once.")
+    _add_wait_timeout(parser, "How long to wait for the job")
+    parser.add_argument("--watch", action="store_true", help="Print progress events to stderr while waiting.")
+
+
+def _add_wait_timeout(parser: argparse.ArgumentParser, what: str) -> None:
+    parser.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=DEFAULT_WAIT_SECONDS,
+        metavar="SECONDS",
+        help=f"{what} (default {DEFAULT_WAIT_SECONDS:.0f}s). It keeps going server-side after.",
+    )
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    job = sub.add_parser("job", parents=[common], help="Read one job; --wait for it to finish.")
+    job.add_argument("job_id", type=job_id, help="The job id.")
+    job.add_argument("--wait", action="store_true", help="Wait until the job finishes.")
+    _add_wait_timeout(job, "With --wait, how long to wait for the job")
+    job.add_argument("--watch", action="store_true", help="Print progress events to stderr while waiting; implies --wait.")
+    add_job_output_args(job)
+    job.set_defaults(run=run_get, family="client", async_submit=False)
+
+    jobs = sub.add_parser("jobs", parents=[common], help="List your jobs, newest first.")
+    jobs.add_argument("--operation", choices=DOCUMENT_OPERATIONS, default=None, help="Only jobs of this operation.")
+    jobs.add_argument("--status", choices=JOB_STATUSES, default=None, help="Only jobs in this status.")
+    jobs.add_argument("--limit", type=int, default=20, help=f"Jobs per page, 1 to {MAX_PAGE_SIZE} (default 20).")
+    pages = jobs.add_mutually_exclusive_group()
+    pages.add_argument("--cursor", default=None, help="Start at this page: the next_cursor of the one before.")
+    pages.add_argument("--all", action="store_true", help="Every job, across every page.")
+    jobs.set_defaults(run=run_list, family="client")
+
+    cancel = sub.add_parser("cancel", parents=[common], help="Cancel a running job, or drop a finished one from `nace jobs`.")
+    cancel.add_argument("job_id", type=job_id, help="The job id.")
+    cancel.set_defaults(run=run_cancel, family="client")
+
+    file = sub.add_parser("file", parents=[common], help="Save a file a job produced: full Markdown, a figure crop, a transcript, ...")
+    file.add_argument("job_id", type=job_id, help="The job id.")
+    file.add_argument("path", help="The link from the job's result, or the part after the job id (parse-images/<ref>).")
+    file.add_argument(
+        "--save",
+        default=None,
+        metavar="PATH",
+        help="Where to write it; - for stdout (default: <job id>.md for a document's Markdown, else <job id>-<kind>[-<digest>] with its extension).",
+    )
+    file.add_argument("--link", action="store_true", help="Print a stored file's five-minute signed link instead of downloading.")
+    _add_wait_timeout(file, "How long to wait for content still being prepared")
+    file.set_defaults(run=run_file, family="client")
+
+    request = sub.add_parser("job-request", parents=[common], help="Print the request a job ran under, as JSON.")
+    request.add_argument("job_id", type=job_id, help="The job id.")
+    request.set_defaults(run=run_request, family="client")
+
+    rows = sub.add_parser("rows", parents=[common], help="Print a parsed sheet's rows as TSV (--json for the page object).")
+    rows.add_argument("job_id", type=job_id, help="The parse job id.")
+    rows.add_argument("path", help="The sheet's rows_url from the parse result, or the part after the job id.")
+    rows.add_argument("--start-row", type=int, default=None, metavar="N", help="First row, numbered from 0 (default 0).")
+    rows.add_argument("--limit", type=int, default=None, metavar="N", help=f"Rows per page, 1 to {MAX_ROWS_PAGE_SIZE} (default 50).")
+    rows.add_argument("--all", action="store_true", help=f"Every row from --start-row on, in pages of --limit (default {MAX_ROWS_PAGE_SIZE}).")
+    rows.set_defaults(run=run_rows, family="client")
+
+    events = sub.add_parser("events", parents=[common], help="Stream a job's progress events, one JSON object per line.")
+    events.add_argument("job_id", type=job_id, help="The job id.")
+    events.add_argument("--last-event-id", default=None, metavar="ID", help="Resume numbering after this event's sequence.")
+    events.set_defaults(run=run_events, family="client")
+
+
+def wait_for(client: NaceClient, job: DocumentJob, args: argparse.Namespace) -> tuple[DocumentJob, int]:
+    """Wait for ``job`` unless ``--async``; status lines go to stderr."""
+    print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    if getattr(args, "async_submit", False):
+        return job, 0
+    try:
+        if job.is_terminal:
+            if job.status != "succeeded":
+                raise NaceJobFailedError(job)
+            return job, 0
+        if getattr(args, "watch", False):
+            _watch(client, job.job_id)
+        job = client.jobs.wait(job.job_id, timeout=args.wait_timeout)
+    except NaceJobFailedError as exc:
+        code = f" [{exc.job.error_code}]" if exc.job.error_code else ""
+        print(f"error:{code} {exc}", file=sys.stderr)
+        return exc.job, 1
+    except NaceJobTimeoutError as exc:
+        print(f"error: {exc}; read it later with `nace job {exc.job.job_id}`", file=sys.stderr)
+        return exc.job, 1
+    print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    return job, 0
+
+
+def _watch(client: NaceClient, job_id: str) -> None:
+    """Progress frames to stderr until the stream ends. Best effort: the wait that follows decides."""
+    try:
+        for event in client.jobs.events(job_id):
+            parts = [str(part) for part in (event.status, event.message) if part]
+            if event.progress:
+                parts.append(" ".join(f"{key}={value}" for key, value in event.progress.items()))
+            if parts:
+                print(f"  {' · '.join(parts)}", file=sys.stderr)
+    except Exception as exc:  # noqa: BLE001 - the poll below still reads the outcome
+        print(f"  (event stream ended: {exc})", file=sys.stderr)
+
+
+def submit_and_report(client: NaceClient, job: DocumentJob, args: argparse.Namespace) -> int:
+    job, code = wait_for(client, job, args)
+    if getattr(args, "async_submit", False):
+        print(job.job_id)
+        return 0
+    if code != 0:
+        if output_mode(args) == "json":
+            emit(job.model_dump_json(indent=2, exclude_none=True), args)
+        return code
+    return render_job(client, job, args)
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    job = client.jobs.get(args.job_id)
+    if args.wait or args.watch:
+        return submit_and_report(client, job, args)
+    return render_job(client, job, args)
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    if args.all:
+        items = list(client.jobs.iter(operation=args.operation, status=args.status))
+        next_cursor = None
+    else:
+        page = client.jobs.list(limit=args.limit, operation=args.operation, status=args.status, cursor=args.cursor)
+        items, next_cursor = list(page.items), page.next_cursor
+    if args.json:
+        print(to_json({"items": [item.model_dump(mode="json", exclude_none=True) for item in items], "next_cursor": next_cursor}))
+        return 0
+    for item in items:
+        print(job_line(item))
+    more = f"--cursor {next_cursor} (or --all)"
+    if not items and next_cursor:
+        # A filtered page can come back empty while later pages still match.
+        print(f"no jobs on this page; more may match: {more}", file=sys.stderr)
+    elif not items:
+        print("no jobs", file=sys.stderr)
+    elif next_cursor:
+        print(f"more jobs: {more}", file=sys.stderr)
+    return 0
+
+
+def run_cancel(client: NaceClient, args: argparse.Namespace) -> int:
+    client.jobs.delete(args.job_id)
+    print(f"cancelled {args.job_id}", file=sys.stderr)
+    return 0
+
+
+def _job_file(job: str, path: str) -> list[str]:
+    """``path``'s segments after the job id: ``[kind, reference...]``. Refuses what the SDK would, before any request."""
+    return resource_path(job, path).removeprefix(f"{job_path(job)}/").split("/")
+
+
+def _default_file_name(job: str, segments: list[str]) -> str:
+    """Where ``nace file`` saves a job file when ``--save`` is not given.
+
+    A stored file's reference is long and opaque (its storage URL, encoded), so it is shortened to a
+    digest that keeps the files of one kind apart.
+    """
+    kind, reference = segments[0], "/".join(segments[1:])
+    extension = _EXTENSIONS.get(kind, "")
+    if kind == "document-content":
+        return f"{job}{extension}"
+    digest = f"-{hashlib.sha256(reference.encode()).hexdigest()[:8]}" if reference else ""
+    return f"{job}-{kind}{digest}{extension}"
+
+
+def run_file(client: NaceClient, args: argparse.Namespace) -> int:
+    # A bad PATH is a usage error here, as it is for `nace rows`.
+    segments = _job_file(args.job_id, args.path)
+    if args.link:
+        try:
+            link = client.jobs.file_link(args.job_id, args.path)
+        except (NaceAPIError, NaceAPIConnectionError):
+            raise
+        except NaceError as exc:
+            # What is left is the answer itself: the file streams, so it has no signed link.
+            raise NaceError(f"{exc} With nace, drop --link to save it.") from None
+        if args.json:
+            print(link.model_dump_json(indent=2))
+        else:
+            print(link.url)
+        return 0
+    save = args.save or _default_file_name(args.job_id, segments)
+    fetch_file(client, args.job_id, args.path, save, wait_timeout=args.wait_timeout)
+    return 0
+
+
+def run_request(client: NaceClient, args: argparse.Namespace) -> int:
+    print(to_json(client.jobs.get_request(args.job_id).model_dump(mode="json")))
+    return 0
+
+
+def _cell(value: Any) -> str:
+    text = "" if value is None else str(value)
+    return text.replace("\\", "\\\\").replace("\t", "\\t").replace("\n", "\\n").replace("\r", "\\r")
+
+
+def _row_pages(client: NaceClient, args: argparse.Namespace) -> Iterator[RowsPage]:
+    """The page ``--start-row``/``--limit`` name, then with ``--all`` every page after it."""
+    # Only an omitted --limit takes the largest page: an explicit 0 still reaches the SDK's range check.
+    limit = MAX_ROWS_PAGE_SIZE if args.all and args.limit is None else args.limit
+    page = client.jobs.rows(args.job_id, args.path, start_row=args.start_row, limit=limit)
+    yield page
+    while args.all and page.rows and (end := page.start_row + len(page.rows)) < page.total_rows:
+        page = client.jobs.rows(args.job_id, args.path, start_row=end, limit=limit)
+        yield page
+
+
+def run_rows(client: NaceClient, args: argparse.Namespace) -> int:
+    pages = _row_pages(client, args)
+    first = last = next(pages)
+    if args.json and not args.all:
+        print(to_json(first.model_dump(mode="json")))
+        return 0
+    rows: list[dict[str, str]] = []
+    if not args.json:
+        print("\t".join(_cell(column.name) for column in first.columns))
+    for page in itertools.chain([first], pages):
+        last = page
+        if args.json:
+            rows.extend(page.rows)
+            continue
+        for row in page.rows:
+            print("\t".join(_cell(row.get(column.name)) for column in first.columns))
+    if args.json:
+        columns = [column.model_dump(mode="json") for column in first.columns]
+        print(to_json({"columns": columns, "rows": rows, "total_rows": last.total_rows}))
+        return 0
+    end = last.start_row + len(last.rows)
+    span = f"rows {first.start_row}-{end - 1}" if end > first.start_row else f"no rows from {first.start_row}"
+    more = f"; more: --start-row {end} (or --all)" if last.rows and end < last.total_rows else ""
+    print(f"{span} of {last.total_rows}{more}", file=sys.stderr)
+    return 0
+
+
+def run_events(client: NaceClient, args: argparse.Namespace) -> int:
+    for event in client.jobs.events(args.job_id, last_event_id=args.last_event_id):
+        print(event.model_dump_json(exclude_none=True), flush=True)
+    return 0

nace_cli/_login.py

@@ -0,0 +1,77 @@
+"""``nace login``, ``nace logout`` and ``nace version``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from getpass import getpass
+
+from nace_sdk.constants import BASE_URL_ENV, DEFAULT_BASE_URL, read_env
+from nace_sdk.credentials import CredentialsError, config_path, login, logout, read_config
+
+
+def _env_base_url() -> str:
+    return read_env(BASE_URL_ENV) or ""
+
+
+def dashboard_url(path: str) -> str:
+    """A dashboard page on the Drex the CLI talks to: ``$NACE_BASE_URL``, else the saved one, else production.
+
+    A config file that can't be read counts as none: this only words a hint.
+    """
+    base = _env_base_url()
+    if not base:
+        try:
+            base = read_config(config_path(), recover=True).get("base_url", "")
+        except OSError:
+            base = ""
+    return f"{(base or DEFAULT_BASE_URL).rstrip('/')}{path}"
+
+
+def add_parsers(sub: argparse._SubParsersAction) -> None:
+    # Building the parser reads no file, so --help and version work whatever state the config is in.
+    host = (_env_base_url() or DEFAULT_BASE_URL).rstrip("/")
+    login_p = sub.add_parser("login", help=f"Save an API key (create one at {host}/dashboard/api-keys).")
+    login_p.add_argument(
+        "--api-key",
+        default=None,
+        metavar="KEY",
+        help="The nace_sk_ key; --api-key - reads it from stdin (hidden at a terminal). Omit to type it hidden.",
+    )
+    login_p.add_argument("--base-url", default=None, metavar="URL", help="Save a different API host with the key.")
+    login_p.set_defaults(run=run_login, family="standalone")
+
+    logout_p = sub.add_parser("logout", help="Delete the saved API key.")
+    logout_p.set_defaults(run=run_logout, family="standalone")
+
+    version = sub.add_parser("version", help="Print CLI and SDK versions.")
+    version.set_defaults(run=run_version, family="standalone")
+
+
+def run_login(args: argparse.Namespace) -> int:
+    key = args.api_key
+    if key == "-":
+        key = getpass("Drex API key: ") if sys.stdin.isatty() else sys.stdin.readline()
+    elif key is None:
+        if not sys.stdin.isatty():
+            raise CredentialsError("pass --api-key KEY (or --api-key - to read stdin) when not in a terminal")
+        key = getpass("Drex API key: ")
+    path = login(key, base_url=args.base_url)
+    print(f"saved API key to {path}", file=sys.stderr)
+    return 0
+
+
+def run_logout(_args: argparse.Namespace) -> int:
+    path = logout()
+    print(f"removed {path}" if path else "no saved API key", file=sys.stderr)
+    return 0
+
+
+def run_version(_args: argparse.Namespace) -> int:
+    from nace_sdk import __version__ as sdk_version  # noqa: PLC0415
+
+    from nace_cli import __version__  # noqa: PLC0415
+
+    print(f"nace {__version__}")
+    print(f"nace-sdk {sdk_version}")
+    return 0

nace_cli/_output.py

@@ -0,0 +1,169 @@
+"""Stdout is the payload; stderr is status. ``-o`` picks the shape of a job's output."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from nace_sdk import DocumentJob, NaceAPIError, NaceClient, NaceError
+from nace_sdk._core.jobs import DEFAULT_WAIT_SECONDS
+
+OUTPUT_CHOICES = ("auto", "md", "json", "result", "id")
+
+
+class CommandFailed(Exception):
+    """A failure after a request went out (exit 1), as opposed to a usage error (exit 2)."""
+
+
+def add_job_output_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-o",
+        "--output",
+        choices=OUTPUT_CHOICES,
+        default="auto",
+        help="auto: Markdown for a parse, the result JSON otherwise; md; json (the whole job); result; id.",
+    )
+    parser.add_argument("--save", default=None, metavar="PATH", help="Write the output to this file instead of stdout.")
+
+
+def output_mode(args: argparse.Namespace) -> str:
+    if getattr(args, "json", False):
+        return "json"
+    return getattr(args, "output", None) or "auto"
+
+
+def to_json(value: Any) -> str:
+    return json.dumps(value, indent=2, ensure_ascii=False)
+
+
+def job_json(job: DocumentJob) -> str:
+    return job.model_dump_json(indent=2, exclude_none=True)
+
+
+def _document(job: DocumentJob) -> dict[str, Any] | None:
+    result = job.result
+    document = result.get("document") if isinstance(result, dict) else None
+    return document if isinstance(document, dict) else None
+
+
+def parse_text(job: DocumentJob) -> str | None:
+    """A parse job's Markdown, else its plain text, else ``None``."""
+    document = _document(job)
+    if document is None:
+        return None
+    for field in ("markdown", "text"):
+        value = document.get(field)
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def emit(text: str, args: argparse.Namespace) -> int:
+    save = getattr(args, "save", None)
+    if not save or save == "-":
+        print(text)
+        return 0
+    target = Path(save)
+    # encoding is explicit: the default follows the locale, so a C/POSIX
+    # environment would fail on any non-ASCII document the job just produced.
+    try:
+        target.write_text(text if text.endswith("\n") else f"{text}\n", encoding="utf-8")
+    except OSError as exc:
+        # The job already ran and was billed: print the result rather than lose it.
+        print(f"error: could not write {target}: {exc.strerror or exc}", file=sys.stderr)
+        print(text)
+        return 1
+    print(f"saved {target}", file=sys.stderr)
+    return 0
+
+
+def fetch_file(client: NaceClient, job_id: str, path: str, save: str | None, *, wait_timeout: float) -> None:
+    """Save one of a job's files to ``save``, or copy it to stdout when ``save`` is unset or ``-``.
+
+    ``path`` comes from a result, or was checked before the call (``nace file``).
+
+    Raises:
+        CommandFailed: The file was still being prepared after ``wait_timeout`` seconds.
+    """
+    try:
+        if save and save != "-":
+            saved = client.jobs.download(job_id, path, save, wait_timeout=wait_timeout)
+            print(f"saved {saved}", file=sys.stderr)
+            return
+        with tempfile.TemporaryDirectory() as tmp:
+            saved = client.jobs.download(job_id, path, Path(tmp) / "file", wait_timeout=wait_timeout)
+            sys.stdout.flush()
+            with saved.open("rb") as handle:
+                shutil.copyfileobj(handle, sys.stdout.buffer)
+            sys.stdout.buffer.flush()
+    except NaceAPIError:
+        raise
+    except NaceError as exc:
+        # The job id and path are checked before the call, so what is left followed a request.
+        raise CommandFailed(str(exc)) from None
+
+
+def emit_markdown(client: NaceClient, job: DocumentJob, markdown: str, args: argparse.Namespace) -> int:
+    """A parse's Markdown, else its text. A large document's result holds only a preview, so its full content is fetched instead.
+
+    That content can be Markdown when only text was asked for: the document service may hold it only that way.
+    A workbook's sheets are pointed at, not fetched.
+    """
+    document = _document(job) or {}
+    content_url = document.get("content_url")
+    if isinstance(content_url, str) and content_url:
+        has_markdown = isinstance(document.get("markdown"), str)
+        note = "" if has_markdown else ", which can be Markdown though you asked only for text"
+        print(f"the result holds a preview of this large document; fetching its full content{note}", file=sys.stderr)
+        try:
+            fetch_file(client, job.job_id, content_url, getattr(args, "save", None), wait_timeout=getattr(args, "wait_timeout", DEFAULT_WAIT_SECONDS))
+        except (NaceError, CommandFailed, OSError) as exc:
+            # The job already ran and was billed: print the preview rather than nothing.
+            print(f"error: could not fetch the full content: {exc}", file=sys.stderr)
+            shown = "Markdown" if has_markdown else "text"
+            print(f"the {shown} below is a preview; fetch the full content with: nace file {job.job_id} {content_url}", file=sys.stderr)
+            print(markdown)
+            return 1
+        return 0
+    spreadsheet = document.get("spreadsheet")
+    sheets = spreadsheet.get("sheets") if isinstance(spreadsheet, dict) else None
+    previews = [sheet for sheet in sheets or [] if isinstance(sheet, dict) and isinstance(sheet.get("content_url"), str)]
+    if previews:
+        print("the Markdown below previews these sheets; save each one in full with:", file=sys.stderr)
+        for sheet in previews:
+            print(f"  {sheet.get('sheet_name')}: nace file {job.job_id} {sheet['content_url']}", file=sys.stderr)
+    return emit(markdown, args)
+
+
+def render_job(client: NaceClient, job: DocumentJob, args: argparse.Namespace) -> int:
+    mode = output_mode(args)
+    if mode == "id":
+        print(job.job_id)
+        return 0
+    if mode == "json":
+        return emit(job_json(job), args)
+    if mode == "md":
+        markdown = parse_text(job)
+        if markdown is None:
+            print("error: this job has no Markdown; use -o auto, json, result or id", file=sys.stderr)
+            return 1
+        return emit_markdown(client, job, markdown, args)
+    if job.result is None:
+        # Not finished, or failed: the job itself is the useful answer.
+        return emit(job_json(job), args)
+    if mode == "auto":
+        markdown = parse_text(job)
+        if markdown is not None:
+            return emit_markdown(client, job, markdown, args)
+    return emit(to_json(job.result), args)
+
+
+def job_line(job: DocumentJob) -> str:
+    credits = f" {job.credits} credits" if job.credits is not None else ""
+    created = f" {job.created_at}" if job.created_at else ""
+    return f"{job.job_id}  {job.kind:<8}  {job.status:<9}{credits}{created}"

nace_cli/_schemas.py

@@ -0,0 +1,135 @@
+"""``nace schemas``, ``nace schema``, and managing a saved extraction schema's versions."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Iterable
+
+from nace_sdk import ExtractionSchema, ExtractionSchemaList, NaceClient
+from nace_sdk._core.endpoints import EXTRACTION_SCHEMA_MAX_PAGE_SIZE
+
+from nace_cli._inputs import read_json
+from nace_cli._output import to_json
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    schemas = sub.add_parser("schemas", parents=[common], help="List saved extraction schemas at their latest version, yours and Nace's, by id.")
+    _add_page_args(schemas, "Schemas")
+    schemas.set_defaults(run=run_list, family="client")
+
+    schema = sub.add_parser("schema", parents=[common], help="Print a saved schema's JSON Schema, at its latest version.")
+    schema.add_argument("schema_id", help="The schema's id (sch_...).")
+    schema.set_defaults(run=run_get, family="client")
+
+    create = sub.add_parser("schema-create", parents=[common], help="Save a new extraction schema.")
+    create.add_argument("name", help="A name for the schema.")
+    create.add_argument("-s", "--schema", required=True, help="JSON Schema: a file path, @FILE, or inline JSON.")
+    create.add_argument("--description", default=None, help="What the schema is for.")
+    create.set_defaults(run=run_create, family="client")
+
+    versions = sub.add_parser("schema-versions", parents=[common], help="List a saved schema's versions, oldest first.")
+    versions.add_argument("schema_id", help="The schema's id (sch_...).")
+    _add_page_args(versions, "Versions")
+    versions.set_defaults(run=run_list_versions, family="client")
+
+    version = sub.add_parser("schema-version", parents=[common], help="Print one version of a saved schema's JSON Schema.")
+    version.add_argument("schema_id", help="The schema's id (sch_...).")
+    version.add_argument("version", type=int, help="The version number.")
+    version.set_defaults(run=run_get_version, family="client")
+
+    add_version = sub.add_parser("schema-version-add", parents=[common], help="Add a new version to an existing schema.")
+    add_version.add_argument("schema_id", help="The schema's id (sch_...).")
+    add_version.add_argument("-s", "--schema", required=True, help="JSON Schema: a file path, @FILE, or inline JSON.")
+    add_version.add_argument("--name", default=None, help="Rename the schema; omit to keep its current name.")
+    add_version.add_argument("--description", default=None, help="Omit to keep the current description.")
+    add_version.set_defaults(run=run_add_version, family="client")
+
+
+def _add_page_args(parser: argparse.ArgumentParser, what: str) -> None:
+    parser.add_argument("--limit", type=int, default=20, help=f"{what} per page, 1 to {EXTRACTION_SCHEMA_MAX_PAGE_SIZE} (default 20).")
+    pages = parser.add_mutually_exclusive_group()
+    pages.add_argument("--cursor", default=None, help="Start at this page: the next_cursor of the one before.")
+    pages.add_argument("--all", action="store_true", help=f"Every {what.lower()[:-1]}, across every page.")
+
+
+def _summary(item: ExtractionSchema) -> str:
+    return f"{item.schema_id}  v{item.version}  {item.name}"
+
+
+def _emit(item: ExtractionSchema, args: argparse.Namespace) -> int:
+    """A schema just saved: its summary line, or the whole record with ``--json``."""
+    if args.json:
+        print(item.model_dump_json(indent=2, by_alias=True, exclude_none=True))
+    else:
+        print(_summary(item))
+    return 0
+
+
+def _emit_schema(item: ExtractionSchema, args: argparse.Namespace) -> int:
+    """A schema read back: the JSON Schema itself on stdout, ready for ``--schema``, and its summary on stderr."""
+    if args.json:
+        print(item.model_dump_json(indent=2, by_alias=True, exclude_none=True))
+        return 0
+    print(_summary(item), file=sys.stderr)
+    if item.schema_ is not None:
+        print(to_json(item.schema_))
+    return 0
+
+
+def _emit_page(args: argparse.Namespace, what: str, page: Callable[[], ExtractionSchemaList], every: Callable[[], Iterable[ExtractionSchema]]) -> int:
+    if args.all:
+        items, next_cursor = list(every()), None
+    else:
+        listed = page()
+        items, next_cursor = list(listed.items), listed.next_cursor
+    if args.json:
+        payload = [item.model_dump(mode="json", by_alias=True, exclude_none=True) for item in items]
+        print(to_json({"items": payload, "next_cursor": next_cursor}))
+        return 0
+    for item in items:
+        print(_summary(item))
+    if not items:
+        print(f"no {what}", file=sys.stderr)
+    if next_cursor:
+        print(f"more {what}: --cursor {next_cursor} (or --all)", file=sys.stderr)
+    return 0
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    schemas = client.extraction_schemas
+    return _emit_page(args, "schemas", lambda: schemas.list(limit=args.limit, cursor=args.cursor), schemas.iter)
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    return _emit_schema(client.extraction_schemas.get(args.schema_id), args)
+
+
+def run_create(client: NaceClient, args: argparse.Namespace) -> int:
+    schema = read_json(args.schema, what="--schema")
+    if not isinstance(schema, dict):
+        raise ValueError("--schema must be a JSON object")
+    created = client.extraction_schemas.create(args.name, schema, description=args.description)
+    return _emit(created, args)
+
+
+def run_list_versions(client: NaceClient, args: argparse.Namespace) -> int:
+    schemas = client.extraction_schemas
+    return _emit_page(
+        args,
+        "versions",
+        lambda: schemas.list_versions(args.schema_id, limit=args.limit, cursor=args.cursor),
+        lambda: schemas.iter_versions(args.schema_id),
+    )
+
+
+def run_get_version(client: NaceClient, args: argparse.Namespace) -> int:
+    return _emit_schema(client.extraction_schemas.get_version(args.schema_id, args.version), args)
+
+
+def run_add_version(client: NaceClient, args: argparse.Namespace) -> int:
+    schema = read_json(args.schema, what="--schema")
+    if not isinstance(schema, dict):
+        raise ValueError("--schema must be a JSON object")
+    created = client.extraction_schemas.create_version(args.schema_id, schema, name=args.name, description=args.description)
+    return _emit(created, args)