nace-cli 0.1.0__tar.gz

nace_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nace AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nace_cli-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: nace-cli
+Version: 0.1.0
+Summary: Nace CLI: calibrated decisions and document jobs from the shell
+Keywords: drex,nace,cli,document-intelligence
+Author: Nace AI
+Author-email: Nace AI <engineering@nace.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: nace-sdk>=0.1,<1
+Requires-Dist: truststore>=0.10.4,<1
+Requires-Python: >=3.11
+Project-URL: Homepage, https://console.nace.ai
+Project-URL: Documentation, https://console.nace.ai/docs/developer-tools/cli
+Description-Content-Type: text/markdown
+
+# nace-cli
+
+`nace` — the [Drex API](https://console.nace.ai/docs) from the shell: calibrated decisions and document jobs.
+
+```bash
+pipx install nace-cli    # or: uv tool install nace-cli
+nace login               # paste a key from https://console.nace.ai/dashboard/api-keys
+```
+
+`nace login` checks the key against Drex before saving it to `~/.nace/config.toml` (mode 0600). `$NACE_API_KEY` and `$NACE_BASE_URL` override the file; `--api-key -` reads the key from stdin for scripts. `nace --version` (or `nace version`) prints the CLI and SDK versions, and `NACE_LOG_LEVEL=debug` logs each request to stderr.
+
+## Decisions
+
+```bash
+nace decide --state "I was charged twice for my March invoice." \
+  --noul "wants_refund=Is the customer asking for a refund?" \
+  --choice "topic=billing,shipping,other: Which topic is it?" \
+  --score "urgency=low,medium,high: How urgent is it?"
+```
+
+```
+wants_refund  noul    0.930
+topic         choice  billing (confidence 0.880)
+urgency       score   1.400 on low < medium < high (confidence 0.500)
+```
+
+`--state` takes text, `@file` or `-` (stdin); a JSON object or array is sent as JSON. Richer questions go in `--questions questions.json`, or a whole request in `--body`. `nace models` lists the models; `-m` picks one. `--json` prints the response body, `request_id` included.
+
+## Documents
+
+```bash
+nace parse https://example.com/invoice.pdf > invoice.md
+nace parse ./invoice.pdf --format markdown,text -p 1-3 --mode high
+nace parse ./locked.pdf --password -          # reads the PDF password from stdin, hidden at a terminal
+nace extract ./invoice.pdf --schema invoice.schema.json
+nace extract job:<parse job id> --schema-id sch_... --schema-version 2
+nace classify ./scan.pdf --class invoice:Invoice --class receipt:Receipt --granularity page
+nace split ./batch.pdf --classes classes.json
+nace ground ./invoice.pdf --target "total=Total due" --target "Net 30"
+```
+
+A `SOURCE` is one of:
+
+- an `https://` URL. The document service picks the parser from the file name's extension, taken from the URL's last path segment; when the link doesn't end in one, name it with `--file-name invoice.pdf`;
+- a local file, uploaded into your workspace first at its file name (`--upload-path` picks another path). The same bytes again reuse the file there; an edited file fails with `path_conflict`: pass another `--upload-path`, or `--on-conflict new_version` to add a version (jobs on that file not yet started then read the new version);
+- `ws:<workspace_id>/<file_id>`, what `nace upload` prints;
+- `job:<parse job id>` to reuse a finished parse (not for `classify`, `-p`, `--mode medium|high` or `--password`).
+
+`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic` (deprecated) asks Ground to match each target by meaning; on PDF, Word and PowerPoint those targets fail with `semantic_mode_deprecated`. Any other request field goes in `--option key=value` (dotted keys nest, JSON values parse) or `--options request.json`; flags win over both, and the source always comes from `SOURCE`.
+
+Each command waits for the job and prints Markdown for a parse, the result JSON otherwise. For a document too large to return inline, `nace parse` fetches the full Markdown instead of the preview; when it can't, it prints the preview, names the `nace file` command that fetches the rest, and exits `1`. `-o json` prints the whole job, `-o result` only the result, `-o id` the job id; `--save PATH` writes it to a file. `--async` prints the job id and returns at once; `--watch` streams progress to stderr; `--wait-seconds N` asks Drex to hold the create up to 60 s; `--wait-timeout` bounds the client-side wait (default 600 s).
+
+## Uploads
+
+```bash
+nace upload ./invoice.pdf --path invoices/2026/invoice.pdf --on-conflict new_version
+nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use upload token for another client
+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.
+
+## Jobs and their files
+
+```bash
+nace jobs --operation parse --status succeeded --limit 50 --cursor <next_cursor>
+nace job <id> --wait                      # --watch implies --wait
+nace events <id>                          # progress, one JSON object per line
+nace job-request <id>                     # the request the job ran under
+nace file <id> <document.content_url>     # full Markdown, saved as <id>.md
+nace file <id> parse-images/<ref> --save figure-1.png
+nace rows <id> <rows_url> --all > sheet.tsv
+nace cancel <id>
+```
+
+`nace file` saves any file a job produced, waiting for Markdown still being prepared. Without `--save` it goes in the current directory as `<id>.md` for a document's Markdown, else `<id>-<kind>-<digest>` with the file's extension. `--link` prints a stored file's five-minute signed link instead.
+
+## Saved extraction schemas
+
+```bash
+nace schema-create Invoice --schema invoice.schema.json
+nace schema-version-add sch_... --schema invoice-v2.schema.json
+nace schemas --all
+nace schema-versions sch_...              # oldest first
+nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for the whole record
+nace schema-version sch_... 1
+```
+
+## 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.
+
+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.
+
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+
+## License
+
+MIT

nace_cli-0.1.0/README.md

@@ -0,0 +1,99 @@
+# nace-cli
+
+`nace` — the [Drex API](https://console.nace.ai/docs) from the shell: calibrated decisions and document jobs.
+
+```bash
+pipx install nace-cli    # or: uv tool install nace-cli
+nace login               # paste a key from https://console.nace.ai/dashboard/api-keys
+```
+
+`nace login` checks the key against Drex before saving it to `~/.nace/config.toml` (mode 0600). `$NACE_API_KEY` and `$NACE_BASE_URL` override the file; `--api-key -` reads the key from stdin for scripts. `nace --version` (or `nace version`) prints the CLI and SDK versions, and `NACE_LOG_LEVEL=debug` logs each request to stderr.
+
+## Decisions
+
+```bash
+nace decide --state "I was charged twice for my March invoice." \
+  --noul "wants_refund=Is the customer asking for a refund?" \
+  --choice "topic=billing,shipping,other: Which topic is it?" \
+  --score "urgency=low,medium,high: How urgent is it?"
+```
+
+```
+wants_refund  noul    0.930
+topic         choice  billing (confidence 0.880)
+urgency       score   1.400 on low < medium < high (confidence 0.500)
+```
+
+`--state` takes text, `@file` or `-` (stdin); a JSON object or array is sent as JSON. Richer questions go in `--questions questions.json`, or a whole request in `--body`. `nace models` lists the models; `-m` picks one. `--json` prints the response body, `request_id` included.
+
+## Documents
+
+```bash
+nace parse https://example.com/invoice.pdf > invoice.md
+nace parse ./invoice.pdf --format markdown,text -p 1-3 --mode high
+nace parse ./locked.pdf --password -          # reads the PDF password from stdin, hidden at a terminal
+nace extract ./invoice.pdf --schema invoice.schema.json
+nace extract job:<parse job id> --schema-id sch_... --schema-version 2
+nace classify ./scan.pdf --class invoice:Invoice --class receipt:Receipt --granularity page
+nace split ./batch.pdf --classes classes.json
+nace ground ./invoice.pdf --target "total=Total due" --target "Net 30"
+```
+
+A `SOURCE` is one of:
+
+- an `https://` URL. The document service picks the parser from the file name's extension, taken from the URL's last path segment; when the link doesn't end in one, name it with `--file-name invoice.pdf`;
+- a local file, uploaded into your workspace first at its file name (`--upload-path` picks another path). The same bytes again reuse the file there; an edited file fails with `path_conflict`: pass another `--upload-path`, or `--on-conflict new_version` to add a version (jobs on that file not yet started then read the new version);
+- `ws:<workspace_id>/<file_id>`, what `nace upload` prints;
+- `job:<parse job id>` to reuse a finished parse (not for `classify`, `-p`, `--mode medium|high` or `--password`).
+
+`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic` (deprecated) asks Ground to match each target by meaning; on PDF, Word and PowerPoint those targets fail with `semantic_mode_deprecated`. Any other request field goes in `--option key=value` (dotted keys nest, JSON values parse) or `--options request.json`; flags win over both, and the source always comes from `SOURCE`.
+
+Each command waits for the job and prints Markdown for a parse, the result JSON otherwise. For a document too large to return inline, `nace parse` fetches the full Markdown instead of the preview; when it can't, it prints the preview, names the `nace file` command that fetches the rest, and exits `1`. `-o json` prints the whole job, `-o result` only the result, `-o id` the job id; `--save PATH` writes it to a file. `--async` prints the job id and returns at once; `--watch` streams progress to stderr; `--wait-seconds N` asks Drex to hold the create up to 60 s; `--wait-timeout` bounds the client-side wait (default 600 s).
+
+## Uploads
+
+```bash
+nace upload ./invoice.pdf --path invoices/2026/invoice.pdf --on-conflict new_version
+nace upload-grant --path inbox/scan.pdf --max-bytes 10000000   # a one-use upload token for another client
+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.
+
+## Jobs and their files
+
+```bash
+nace jobs --operation parse --status succeeded --limit 50 --cursor <next_cursor>
+nace job <id> --wait                      # --watch implies --wait
+nace events <id>                          # progress, one JSON object per line
+nace job-request <id>                     # the request the job ran under
+nace file <id> <document.content_url>     # full Markdown, saved as <id>.md
+nace file <id> parse-images/<ref> --save figure-1.png
+nace rows <id> <rows_url> --all > sheet.tsv
+nace cancel <id>
+```
+
+`nace file` saves any file a job produced, waiting for Markdown still being prepared. Without `--save` it goes in the current directory as `<id>.md` for a document's Markdown, else `<id>-<kind>-<digest>` with the file's extension. `--link` prints a stored file's five-minute signed link instead.
+
+## Saved extraction schemas
+
+```bash
+nace schema-create Invoice --schema invoice.schema.json
+nace schema-version-add sch_... --schema invoice-v2.schema.json
+nace schemas --all
+nace schema-versions sch_...              # oldest first
+nace schema sch_... > invoice.schema.json # the JSON Schema itself; --json for the whole record
+nace schema-version sch_... 1
+```
+
+## 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.
+
+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.
+
+Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, exit codes).
+
+## License
+
+MIT

nace_cli-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "nace-cli"
+version = "0.1.0"
+description = "Nace CLI: calibrated decisions and document jobs from the shell"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "drex",
+    "nace",
+    "cli",
+    "document-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "nace-sdk>=0.1,<1",
+    "truststore>=0.10.4,<1",
+]
+
+[[project.authors]]
+name = "Nace AI"
+email = "engineering@nace.ai"
+
+[project.urls]
+Homepage = "https://console.nace.ai"
+Documentation = "https://console.nace.ai/docs/developer-tools/cli"
+
+[project.scripts]
+nace = "nace_cli._entrypoint:main"
+
+[tool.uv.sources.nace-sdk]
+workspace = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 150
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "RUF",
+    "ASYNC",
+    "SIM",
+    "BLE",
+    "PLC0415",
+]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+    "ASYNC109",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [
+    "src",
+    "tests",
+]
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"

nace_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,66 @@
+[project]
+name = "nace-cli"
+version = "0.1.0"
+description = "Nace CLI: calibrated decisions and document jobs from the shell"
+authors = [
+    { name = "Nace AI", email = "engineering@nace.ai" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "drex",
+    "nace",
+    "cli",
+    "document-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "nace-sdk>=0.1,<1",
+    "truststore>=0.10.4,<1",
+]
+
+[project.urls]
+Homepage = "https://console.nace.ai"
+Documentation = "https://console.nace.ai/docs/developer-tools/cli"
+
+[project.scripts]
+nace = "nace_cli._entrypoint:main"
+
+[tool.uv.sources]
+nace-sdk = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 150
+fix = true
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF", "ASYNC", "SIM", "BLE", "PLC0415"]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+    "ASYNC109",  # `timeout` on jobs.wait is a polling budget, not a cancel scope
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+asyncio_mode = "auto"
+addopts = ["--strict-markers", "--tb=short"]

nace_cli-0.1.0/src/nace_cli/__init__.py

@@ -0,0 +1,9 @@
+"""``nace`` — the Nace CLI.
+
+Decisions (``POST /v1/systemone``), document jobs and uploads
+(``/v1/documents/*``) and saved extraction schemas (``/v1/extraction-schemas``)
+over ``nace-sdk``. Credentials come from
+``$NACE_API_KEY`` / ``$NACE_BASE_URL`` or ``~/.nace/config.toml``.
+"""
+
+__version__ = "0.1.0"

nace_cli-0.1.0/src/nace_cli/_cli.py

@@ -0,0 +1,151 @@
+"""``nace`` entry point: parser, client construction, and error reporting.
+
+Exit codes: ``0`` success, ``1`` an API or job failure, ``2`` a usage or
+configuration error. Stdout carries the payload; stderr carries status, so
+``nace parse doc.pdf > doc.md`` captures only the document.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from typing import Any
+
+from nace_sdk import NaceAPIConnectionError, NaceAPIError, NaceClient, NaceError, NaceJobFailedError, NaceJobTimeoutError
+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._output import CommandFailed
+
+#: Long enough for a decision (Drex holds one up to 60 s) and for a document
+#: create that waits server-side; job waits have their own budget (--wait-timeout).
+DEFAULT_TIMEOUT_SECONDS = 120.0
+_ISSUE_LIMIT = 5
+
+
+class _StderrHandler(logging.Handler):
+    """Writes to whatever ``sys.stderr`` is at the time, so redirection and capture see SDK logs."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        print(self.format(record), file=sys.stderr)
+
+
+_SDK_LOG = _StderrHandler()
+_SDK_LOG.setFormatter(logging.Formatter("nace_sdk %(levelname)s %(message)s"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.show_version:
+        return _login.run_version(args)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    _log_to_stderr()
+    try:
+        if args.family == "standalone":
+            return args.run(args)
+        credentials = resolve_credentials()
+        with NaceClient(api_key=credentials.api_key, base_url=credentials.base_url, timeout=args.timeout) as client:
+            return args.run(client, args)
+    except CredentialsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except NaceAPIError as exc:
+        report_status_error(exc)
+        return 1
+    except (NaceAPIConnectionError, NaceJobFailedError, NaceJobTimeoutError, CommandFailed) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except NaceError as exc:
+        # Raised before any request: a bad argument the SDK refused locally.
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _log_to_stderr() -> None:
+    """``$NACE_LOG_LEVEL`` sets the SDK logger's level when it loads; the CLI gives those records a place to go."""
+    logger = logging.getLogger("nace_sdk")
+    if read_env(LOG_LEVEL_ENV) and _SDK_LOG not in logger.handlers:
+        logger.addHandler(_SDK_LOG)
+
+
+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
+    errors = exc.detail.get("errors") if isinstance(exc.detail, dict) else None
+    if not isinstance(errors, list):
+        return []
+    lines = []
+    for entry in errors:
+        if not isinstance(entry, dict):
+            continue
+        location = entry.get("loc")
+        path = entry.get("path") or (".".join(str(part) for part in location if part != "body") if isinstance(location, list) else "")
+        lines.append({"path": path, "message": entry.get("message") or entry.get("msg") or ""})
+    return lines
+
+
+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)
+    tag = f" [{label}]" if label else ""
+    request = f" ({exc.request_id})" if exc.request_id else ""
+    print(f"error: {exc.status}{tag} {exc.message}{request}", file=sys.stderr)
+    issues = _validation_lines(exc)
+    for issue in issues[:_ISSUE_LIMIT]:
+        where = f"{issue.get('path')}: " if issue.get("path") else ""
+        print(f"  - {where}{issue.get('message', '')}", file=sys.stderr)
+    if len(issues) > _ISSUE_LIMIT:
+        print(f"  (+{len(issues) - _ISSUE_LIMIT} more)", file=sys.stderr)
+    if exc.status == 402:
+        billing = _login.dashboard_url("/dashboard/billing")
+        # payment_required is an unpaid invoice: a top-up doesn't lift it, paying the invoice does.
+        if exc.type == "payment_required":
+            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)
+    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.",
+            file=sys.stderr,
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nace",
+        description=(
+            "Nace CLI: calibrated decisions and document jobs. 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."
+        ),
+    )
+    parser.add_argument("--version", dest="show_version", action="store_true", help="Print CLI and SDK versions (same as `nace version`).")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Print the raw response JSON.")
+    common.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        metavar="SECONDS",
+        help=f"Per-request HTTP timeout (default {DEFAULT_TIMEOUT_SECONDS:.0f}s).",
+    )
+    sub = parser.add_subparsers(dest="command")
+    _login.add_parsers(sub)
+    _decide.add_parsers(sub, common)
+    _docops.add_parsers(sub, common)
+    _jobs.add_parsers(sub, common)
+    _schemas.add_parsers(sub, common)
+    return parser
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())