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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nace-cli
-Version: 0.2.0
+Version: 0.4.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.2,<1
+Requires-Dist: nace-sdk>=0.6.0,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://console.nace.ai
@@ -114,7 +114,7 @@ nace schema-version sch_... 1
 ## Workspaces and search
 
 ```bash
-nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+nace workspace-create fy25-audit
 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
@@ -122,16 +122,29 @@ 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`.
 
+## Domains
+
+A domain is the two-level taxonomy (group and subgroup classes) a workspace classifies its files against. Nace provides some; your account can author its own. A draft is edited in place and published once; a published or Nace-provided domain is frozen, so duplicate it and edit the copy.
+
+```bash
+nace domains list --owner platform --status published   # domains (N):, then <domain_id>  <slug>  v<n>  <status>  <owner>  <display_name>
+nace domains get --id <domain_id>                       # the domain's line, then its classes
+nace domains create --slug leases --display-name "Lease files" --taxonomy leases.taxonomy.json   # --taxonomy: JSON, @FILE or -
+nace domains update --id <domain_id> --display-name "Leases"
+nace domains publish --id <domain_id>                   # one-way; a taxonomy that fails validation exits 1 and lists each error
+nace domains duplicate --id <domain_id>                 # a draft copy of any domain you see
+nace workspace-create fy25-leases --domain leases  # a published domain's slug; it can't be changed later
+```
+
 ## Output and exit codes
 
 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`, `schema-version-add` and `workspace-create` 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`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
 
 Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 

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

@@ -89,7 +89,7 @@ nace schema-version sch_... 1
 ## Workspaces and search
 
 ```bash
-nace workspace-create fy25-audit --global-context "Entity: Acme Holdings Ltd."
+nace workspace-create fy25-audit
 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
@@ -97,16 +97,29 @@ 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`.
 
+## Domains
+
+A domain is the two-level taxonomy (group and subgroup classes) a workspace classifies its files against. Nace provides some; your account can author its own. A draft is edited in place and published once; a published or Nace-provided domain is frozen, so duplicate it and edit the copy.
+
+```bash
+nace domains list --owner platform --status published   # domains (N):, then <domain_id>  <slug>  v<n>  <status>  <owner>  <display_name>
+nace domains get --id <domain_id>                       # the domain's line, then its classes
+nace domains create --slug leases --display-name "Lease files" --taxonomy leases.taxonomy.json   # --taxonomy: JSON, @FILE or -
+nace domains update --id <domain_id> --display-name "Leases"
+nace domains publish --id <domain_id>                   # one-way; a taxonomy that fails validation exits 1 and lists each error
+nace domains duplicate --id <domain_id>                 # a draft copy of any domain you see
+nace workspace-create fy25-leases --domain leases  # a published domain's slug; it can't be changed later
+```
+
 ## Output and exit codes
 
 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`, `schema-version-add` and `workspace-create` 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`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
 
 Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.2.0"
+version = "0.4.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.2,<1",
+    "nace-sdk>=0.6.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.2.0"
+version = "0.4.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.2,<1",
+    "nace-sdk>=0.6.0,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.2.0 → nace_cli-0.4.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.2.0"
+__version__ = "0.4.0"

nace_cli-0.4.0/src/nace_cli/_browser.py

@@ -0,0 +1,241 @@
+"""``nace browser run|get|list|cancel|artifacts``: a cloud browser agent that does a task on the sites you allow.
+
+A run is billed once, when it ends: its Drex Max and LLM tokens and its browser seconds, never more
+than ``--max-cost``. Reading and listing runs is free;
+a run that fails, times out, or is cancelled before completion is not charged.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+from nace_sdk import BROWSER_RUN_STATUSES, BrowserRun, BrowserRunRef, NaceBrowserRunTimeoutError, NaceClient
+from nace_sdk._core.endpoints import BROWSER_RUN_MAX_PAGE_SIZE, DEFAULT_BROWSER_WAIT_SECONDS
+
+from nace_cli._inputs import read_json
+from nace_cli._output import to_json
+from nace_cli._schemas import _add_page_args, _emit_page
+
+#: What `--max-cost`, `--max-seconds` and `--max-llm-calls` take, as Drex accepts them.
+MAX_COST_RANGE = (0.01, 1.0)
+MAX_SECONDS_RANGE = (1, 1800)
+MAX_LLM_CALLS_RANGE = (1, 100)
+#: How much of a run's task a `nace browser list` line shows.
+_TASK_CHARS = 60
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    browser = sub.add_parser(
+        "browser",
+        help="Browser runs: a cloud browser agent does a task on the sites you allow and returns an answer.",
+        description="Browser runs: a cloud browser agent does a task on the sites you allow and returns an answer.",
+    )
+    commands = browser.add_subparsers(dest="browser_command", metavar="{run,get,list,cancel,artifacts}", required=True)
+
+    run = commands.add_parser("run", parents=[common], help="Start a run and wait for it; print its answer.")
+    run.add_argument("task", help="What the agent should do, in plain language: 1 to 4000 characters.")
+    run.add_argument("--start-url", required=True, metavar="URL", help="The page to open first: an http:// or https:// URL.")
+    run.add_argument(
+        "--allow",
+        dest="allowed_origins",
+        action="append",
+        default=None,
+        metavar="ORIGIN",
+        help="An origin the browser may load, such as https://shop.example.com. Repeatable. Without it, only the start URL's origin.",
+    )
+    run.add_argument(
+        "--answer-schema", default=None, metavar="SCHEMA", help="JSON Schema for a structured answer: a file path, @FILE, inline JSON, or -."
+    )
+    run.add_argument(
+        "--max-cost", type=float, default=None, metavar="USD", help="The most the run may be charged, in US dollars, 0.01 up to 1 (default 0.04)."
+    )
+    run.add_argument("--max-seconds", type=int, default=None, metavar="N", help="How long the run may browse, 1 to 1800 seconds (default 600).")
+    run.add_argument(
+        "--max-llm-calls", type=int, default=None, metavar="N", help="How many planning and reading calls it may make, 1 to 100 (default 20)."
+    )
+    run.add_argument(
+        "--metadata", action="append", default=None, metavar="KEY=VALUE", help="A string of your own, returned with the run. Repeatable."
+    )
+    run.add_argument("--idempotency-key", default=None, metavar="KEY", help="The same key returns the same run instead of starting another.")
+    run.add_argument("--no-wait", action="store_true", help="Print the run id and return at once.")
+    run.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=DEFAULT_BROWSER_WAIT_SECONDS,
+        metavar="SECONDS",
+        help=f"How long to wait for the run (default {DEFAULT_BROWSER_WAIT_SECONDS:.0f}s). It keeps going server-side after.",
+    )
+    run.set_defaults(run=run_run, family="client")
+
+    get = commands.add_parser("get", parents=[common], help="Read one run: its status, answer and cost.")
+    get.add_argument("run_id", help="The run's id (brun_...).")
+    get.set_defaults(run=run_get, family="client")
+
+    listing = commands.add_parser("list", parents=[common], help="List your runs, newest first.")
+    listing.add_argument("--status", choices=BROWSER_RUN_STATUSES, default=None, help="Only runs in this status.")
+    _add_page_args(listing, "Runs", maximum=BROWSER_RUN_MAX_PAGE_SIZE)
+    listing.set_defaults(run=run_list, family="client")
+
+    cancel = commands.add_parser("cancel", parents=[common], help="Cancel a queued or running run.")
+    cancel.add_argument("run_id", help="The run's id (brun_...).")
+    cancel.set_defaults(run=run_cancel, family="client")
+
+    artifacts = commands.add_parser("artifacts", parents=[common], help="List a run's artifacts, such as screenshots, with their links.")
+    artifacts.add_argument("run_id", help="The run's id (brun_...).")
+    artifacts.set_defaults(run=run_artifacts, family="client")
+
+
+def start_origin(start_url: str) -> str:
+    """The origin of ``start_url`` (``https://shop.example.com``), which a run without ``--allow`` may load.
+
+    Raises:
+        ValueError: Not an ``http://`` or ``https://`` URL with a host.
+    """
+    parts = urlsplit(start_url.strip())
+    host = parts.netloc.rpartition("@")[2].lower()
+    if parts.scheme.lower() not in ("http", "https") or not host:
+        raise ValueError(f"--start-url must be an http:// or https:// URL, got {start_url!r}")
+    return f"{parts.scheme.lower()}://{host}"
+
+
+def _in_range(flag: str, value: float | None, bounds: tuple[float, float]) -> None:
+    low, high = bounds
+    if value is not None and not low <= value <= high:
+        raise ValueError(f"{flag} must be between {low:g} and {high:g}, got {value:g}")
+
+
+def _limits(args: argparse.Namespace) -> dict[str, Any] | None:
+    """The limits named on the command line; one left out takes Drex's default."""
+    _in_range("--max-cost", args.max_cost, MAX_COST_RANGE)
+    _in_range("--max-seconds", args.max_seconds, MAX_SECONDS_RANGE)
+    _in_range("--max-llm-calls", args.max_llm_calls, MAX_LLM_CALLS_RANGE)
+    limits = {"max_cost_usd": args.max_cost, "max_seconds": args.max_seconds, "max_llm_calls": args.max_llm_calls}
+    named = {key: value for key, value in limits.items() if value is not None}
+    return named or None
+
+
+def _metadata(pairs: list[str] | None) -> dict[str, str] | None:
+    if not pairs:
+        return None
+    metadata: dict[str, str] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise ValueError(f"--metadata needs KEY=VALUE, got {pair!r}")
+        metadata[key] = value
+    return metadata
+
+
+def _status_line(run: BrowserRun | BrowserRunRef) -> str:
+    kind = run.outcome.kind if isinstance(run, BrowserRun) and run.outcome is not None else None
+    return f"browser run {run.id} {run.status}" + (f" ({kind})" if kind and kind != run.status else "")
+
+
+def _run_json(run: BrowserRun | BrowserRunRef) -> str:
+    return run.model_dump_json(indent=2, exclude_none=True)
+
+
+def _print_run(run: BrowserRun, args: argparse.Namespace) -> None:
+    """The run whole with ``--json``; otherwise its answer on stdout and its status, reason and cost on stderr."""
+    if args.json:
+        print(_run_json(run))
+        return
+    print(_status_line(run), file=sys.stderr)
+    if run.outcome is not None and run.outcome.reason:
+        print(f"  {run.outcome.reason}", file=sys.stderr)
+    if run.final_url:
+        print(f"  final url: {run.final_url}", file=sys.stderr)
+    if run.usage is not None and run.usage.cost_usd is not None:
+        print(f"  cost: ${run.usage.cost_usd:.4f}", file=sys.stderr)
+    if run.answer is not None:
+        print(to_json(run.answer))
+    elif run.answer_text:
+        print(run.answer_text)
+
+
+def run_run(client: NaceClient, args: argparse.Namespace) -> int:
+    """Start a run, then wait for it unless ``--no-wait``. A run that ended other than ``succeeded`` exits ``1``."""
+    origin = start_origin(args.start_url)
+    origins = args.allowed_origins or [origin]
+    limits = _limits(args)
+    metadata = _metadata(args.metadata)
+    answer_schema = None
+    if args.answer_schema is not None:
+        answer_schema = read_json(args.answer_schema, what="--answer-schema")
+        if not isinstance(answer_schema, dict):
+            raise ValueError("--answer-schema must be a JSON object")
+    if not args.wait_timeout >= 0:
+        raise ValueError("--wait-timeout must be 0 or more seconds")
+    runs = client.browser_runs
+    created = runs.create(
+        task=args.task,
+        start_url=args.start_url,
+        allowed_origins=origins,
+        answer_schema=answer_schema,
+        limits=limits,
+        metadata=metadata,
+        idempotency_key=args.idempotency_key,
+    )
+    print(_status_line(created), file=sys.stderr)
+    if args.no_wait:
+        print(_run_json(created) if args.json else created.id)
+        return 0
+    try:
+        run = runs.wait(created.id, timeout=args.wait_timeout)
+    except NaceBrowserRunTimeoutError as exc:
+        print(f"error: {exc}; read it later with `nace browser get {exc.run.id}`", file=sys.stderr)
+        print(_run_json(exc.run) if args.json else exc.run.id)
+        return 1
+    _print_run(run, args)
+    if run.status == "succeeded":
+        return 0
+    kind = f" [{run.outcome.kind}]" if run.outcome is not None else ""
+    print(f"error: browser run {run.id} ended {run.status}{kind}", file=sys.stderr)
+    return 1
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    _print_run(client.browser_runs.get(args.run_id), args)
+    return 0
+
+
+def _list_line(run: BrowserRun) -> str:
+    task = run.task if len(run.task) <= _TASK_CHARS else f"{run.task[: _TASK_CHARS - 1]}…"
+    cost = f"${run.usage.cost_usd:.4f}" if run.usage is not None and run.usage.cost_usd is not None else "-"
+    return f"{run.id}  {run.status}  {cost}  {run.created_at}  {task}".rstrip()
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    runs = client.browser_runs
+    return _emit_page(
+        args,
+        "runs",
+        lambda: runs.list(limit=args.limit, status=args.status, cursor=args.cursor),
+        lambda: runs.iter_all(status=args.status),
+        summary=_list_line,
+    )
+
+
+def run_cancel(client: NaceClient, args: argparse.Namespace) -> int:
+    ref = client.browser_runs.cancel(args.run_id)
+    if args.json:
+        print(_run_json(ref))
+    else:
+        print(_status_line(ref), file=sys.stderr)
+    return 0
+
+
+def run_artifacts(client: NaceClient, args: argparse.Namespace) -> int:
+    listed = client.browser_runs.artifacts(args.run_id)
+    if args.json:
+        print(to_json({"items": [item.model_dump(mode="json", exclude_none=True) for item in listed.items]}))
+        return 0
+    for item in listed.items:
+        step = f"step {item.step}" if item.step is not None else "-"
+        print(f"{item.kind}  {step}  {item.url or '-'}")
+    if not listed.items:
+        print("no artifacts", file=sys.stderr)
+    return 0

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

@@ -16,7 +16,7 @@ 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, _search, _upload, _workspaces
+from nace_cli import _browser, _decide, _docops, _domains, _jobs, _login, _schemas, _search, _storage, _upload, _workspaces
 from nace_cli._inputs import check_one_stdin_flag
 from nace_cli._output import CommandFailed
 
@@ -82,6 +82,14 @@ def _validation_lines(exc: NaceAPIError) -> list[dict[str, Any]]:
     """Where a request failed validation: ``error.issues``, else the document routes' ``error.detail.errors``."""
     if exc.issues:
         return exc.issues
+    if isinstance(exc.detail, dict) and isinstance(exc.detail.get("validation"), dict):
+        # A refused domain publish: `detail.validation.errors` is each `{code, path, message}` to fix.
+        found = exc.detail["validation"].get("errors")
+        return [
+            {"path": entry.get("path") or "", "message": f"{entry.get('message') or ''} ({entry.get('code') or 'invalid'})"}
+            for entry in found or []
+            if isinstance(entry, dict)
+        ]
     errors = exc.detail.get("errors") if isinstance(exc.detail, dict) else None
     if not isinstance(errors, list):
         return []
@@ -101,6 +109,11 @@ _WORKSPACE_HINTS = {
     "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.",
+    "storage_connection_unavailable": (
+        "`nace storage list` lists your account's connections. A deployment without customer storage answers this to every call."
+    ),
+    "storage_connection_not_ready": "Validate the connection first: `nace storage validate --id ID --wait`.",
+    "storage_credentials_refused": "Check the role ARN, or the Entra tenant, client id and secret, then run `nace storage credentials` again.",
 }
 
 
@@ -144,7 +157,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="nace",
         description=(
-            "Nace CLI: calibrated decisions, document jobs, workspaces and search. Credentials come from "
+            "Nace CLI: calibrated decisions, document jobs, workspaces, storage connections, search and browser runs. 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."
         ),
@@ -167,7 +180,10 @@ def build_parser() -> argparse.ArgumentParser:
     _jobs.add_parsers(sub, common)
     _schemas.add_parsers(sub, common)
     _workspaces.add_parsers(sub, common)
+    _domains.add_parsers(sub, common)
+    _storage.add_parsers(sub, common)
     _search.add_parsers(sub, common)
+    _browser.add_parsers(sub, common)
     return parser
 
 

nace_cli-0.4.0/src/nace_cli/_domains.py

@@ -0,0 +1,178 @@
+"""Domains: the taxonomies a workspace classifies its files against.
+
+``nace domains`` takes an action: ``list`` lists them as ``nace workspaces`` lists workspaces, ``get``
+reads one with its classes, and ``create``, ``update``, ``publish`` and ``duplicate`` write them. Every
+input is a flag (``--id``, ``--slug``, ...). A draft is edited in place and published once, and a
+published or platform domain is frozen, so ``nace domains duplicate`` copies it into a draft.
+``nace workspace-create --domain SLUG`` pins a published one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from nace_sdk import Domain, DomainSummary, DomainWrite, NaceClient
+from nace_sdk._core.endpoints import DOMAIN_MAX_PAGE_SIZE
+
+from nace_cli._inputs import read_json
+from nace_cli._output import CommandFailed
+from nace_cli._schemas import _add_page_args
+from nace_cli._workspaces import _emit_listing, _total
+
+#: The two owners a domain has, for ``nace domains list --owner``.
+OWNERS = ("platform", "tenant")
+#: The two statuses a domain version has, for ``nace domains list --status``.
+STATUSES = ("draft", "published")
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    domains = sub.add_parser("domains", help="List, read, create, update, publish and duplicate domains.")
+    actions = domains.add_subparsers(dest="domains_action", metavar="{list,get,create,update,publish,duplicate}", required=True)
+
+    listing = actions.add_parser("list", parents=[common], help="List the domains your account sees: Nace's and its own.")
+    listing.add_argument("--owner", default=None, choices=OWNERS, help="Only the platform's domains, or only the account's own.")
+    listing.add_argument("--status", default=None, choices=STATUSES, help="Only drafts, or only published versions.")
+    listing.add_argument("--slug", default=None, metavar="SLUG", help="Only the versions of this slug.")
+    _add_page_args(listing, "Domains", default=50, maximum=DOMAIN_MAX_PAGE_SIZE)
+    listing.set_defaults(run=run_list, family="client")
+
+    show = actions.add_parser("get", parents=[common], help="Print a domain with its taxonomy classes.")
+    show.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The domain's id, as `nace domains list` lists it.")
+    show.set_defaults(run=run_get, family="client")
+
+    create = actions.add_parser("create", parents=[common], help="Create a draft domain owned by your account.")
+    create.add_argument(
+        "--slug", required=True, metavar="SLUG", help="The name a workspace is created against with --domain. It can't be changed later."
+    )
+    create.add_argument("--display-name", required=True, metavar="NAME", help="The name people see.")
+    create.add_argument("--taxonomy", default=None, metavar="JSON", help='The classes, as {"classes": [...]}: inline JSON, @FILE, a path, or -.')
+    create.set_defaults(run=run_create, family="client")
+
+    update = actions.add_parser("update", parents=[common], help="Rename a draft domain or replace its taxonomy.")
+    update.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The draft's id.")
+    update.add_argument("--display-name", default=None, metavar="NAME", help="The new name people see.")
+    update.add_argument("--taxonomy", default=None, metavar="JSON", help="The whole new taxonomy: inline JSON, @FILE, a path, or -.")
+    update.set_defaults(run=run_update, family="client")
+
+    publish = actions.add_parser("publish", parents=[common], help="Publish a draft domain so workspaces can use it. It can't be undone.")
+    publish.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The draft's id.")
+    publish.set_defaults(run=run_publish, family="client")
+
+    duplicate = actions.add_parser("duplicate", parents=[common], help="Copy any domain you can see into a new draft.")
+    duplicate.add_argument("--id", dest="domain_id", required=True, metavar="DOMAIN_ID", help="The id of the domain to copy.")
+    duplicate.set_defaults(run=run_duplicate, family="client")
+
+
+# --- Rendering ----------------------------------------------------------------------------------
+
+
+def _domain_line(item: DomainSummary) -> str:
+    return f"{item.domain_id}  {item.slug}  v{item.version}  {item.status}  {item.owner}  {item.display_name}"
+
+
+def _written_line(item: DomainSummary) -> str:
+    return f"{item.domain_id}  {item.slug}  v{item.version}  {item.status}"
+
+
+def _one_line(text: Any) -> str:
+    return " ".join(str(text or "").split())
+
+
+def _domain_detail(item: Domain) -> str:
+    """The domain's line, ``inherits:`` when it has a parent, then ``classes (N):`` with each class and its aliases."""
+    lines = [_domain_line(item)]
+    if item.parent_slug:
+        lines.append(f"inherits: {item.parent_slug}")
+    classes = [entry for entry in item.taxonomy.get("classes") or [] if isinstance(entry, dict)]
+    lines.append(f"classes ({len(classes)}):")
+    for entry in classes:
+        description = _one_line(entry.get("description"))
+        lines.append(f"  {entry.get('group')} / {entry.get('subgroup')}{f': {description}' if description else ''}")
+        aliases = [str(alias) for alias in entry.get("aliases") or []]
+        if aliases:
+            lines.append(f"    aliases: {', '.join(aliases)}")
+    return "\n".join(lines)
+
+
+def _validation_errors(written: DomainWrite) -> list[dict[str, Any]]:
+    return [dict(error) for error in written.validation.errors]
+
+
+def _error_line(error: dict[str, Any]) -> str:
+    where = f"{error['path']}: " if error.get("path") else ""
+    return f"  - {where}{error.get('message', '')} ({error.get('code', 'invalid')})"
+
+
+def _emit_write(written: DomainWrite, args: argparse.Namespace) -> int:
+    """The saved domain's line, or ``{domain, validation}`` with ``--json``; what validation found goes to stderr."""
+    if args.json:
+        print(written.model_dump_json(indent=2, by_alias=True, exclude_none=True))
+        return 0
+    print(_written_line(written.domain))
+    errors = _validation_errors(written)
+    if errors:
+        print(f"the taxonomy has {len(errors)} validation errors:", file=sys.stderr)
+        for error in errors:
+            print(_error_line(error), file=sys.stderr)
+    return 0
+
+
+def _taxonomy(value: str | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    loaded = read_json(value, what="--taxonomy")
+    if not isinstance(loaded, dict):
+        raise ValueError("--taxonomy must be a JSON object")
+    return loaded
+
+
+# --- Commands -----------------------------------------------------------------------------------
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    domains = client.domains
+    filters = {"owner": args.owner, "status": args.status, "slug": args.slug}
+    return _emit_listing(
+        args,
+        "domains",
+        lambda: domains.list(limit=args.limit, cursor=args.cursor, **filters),
+        lambda: domains.iter(**filters),
+        line=_domain_line,
+        extra=lambda page, items: {"total_count": _total(page, items)},
+    )
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    item = client.domains.get(args.domain_id.strip())
+    print(item.model_dump_json(indent=2, by_alias=True, exclude_none=True) if args.json else _domain_detail(item))
+    return 0
+
+
+def run_create(client: NaceClient, args: argparse.Namespace) -> int:
+    if not args.slug.strip():
+        raise ValueError("--slug must not be blank")
+    if not args.display_name.strip():
+        raise ValueError("--display-name must not be blank")
+    written = client.domains.create(slug=args.slug.strip(), display_name=args.display_name, taxonomy=_taxonomy(args.taxonomy))
+    return _emit_write(written, args)
+
+
+def run_update(client: NaceClient, args: argparse.Namespace) -> int:
+    if args.display_name is None and args.taxonomy is None:
+        raise ValueError("pass at least one change: --display-name or --taxonomy")
+    written = client.domains.update(args.domain_id.strip(), display_name=args.display_name, taxonomy=_taxonomy(args.taxonomy))
+    return _emit_write(written, args)
+
+
+def run_publish(client: NaceClient, args: argparse.Namespace) -> int:
+    written = client.domains.publish(args.domain_id.strip())
+    code = _emit_write(written, args)
+    if not written.validation.valid:
+        raise CommandFailed("the domain was not published: fix the taxonomy errors above")
+    return code
+
+
+def run_duplicate(client: NaceClient, args: argparse.Namespace) -> int:
+    return _emit_write(client.domains.duplicate(args.domain_id.strip()), args)

{nace_cli-0.2.0 → nace_cli-0.4.0}/src/nace_cli/_inputs.py

@@ -22,10 +22,11 @@ STDIN_FLAGS = {
     "targets_file": "--targets",
     "password": "--password",
     "access": "--access",
-    "retention_policy": "--retention-policy",
-    "knowledge_graph": "--knowledge-graph",
+    "taxonomy": "--taxonomy",
     "output_schema": "--output-schema",
     "clarification_answers": "--clarification-answers",
+    "answer_schema": "--answer-schema",
+    "client_secret_file": "--client-secret-file",
 }