nace-cli 0.3.0__tar.gz → 0.4.1__tar.gz

{nace_cli-0.3.0 → nace_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nace-cli
-Version: 0.3.0
+Version: 0.4.1
 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.3.0,<1
+Requires-Dist: nace-sdk>=0.6.2,<1
 Requires-Dist: truststore>=0.10.4,<1
 Requires-Python: >=3.11
 Project-URL: Homepage, https://console.nace.ai
@@ -151,3 +151,8 @@ Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in,
 ## License
 
 MIT
+
+
+## Custom and on-prem servers
+
+Set `NACE_API_KEY` and `NACE_BASE_URL=https://nace.customer.example` in the process using the CLI or MCP server; no login or profile is required. Environment values take precedence over saved configuration. Alternatively, `nace login --base-url https://nace.customer.example --api-key - < key.txt` validates and saves the key and actual server URL for both tools. For unattended profile use, mount a mode-0600 file and set `NACE_CONFIG_PATH` to it.

{nace_cli-0.3.0 → nace_cli-0.4.1}/README.md

@@ -126,3 +126,8 @@ Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in,
 ## License
 
 MIT
+
+
+## Custom and on-prem servers
+
+Set `NACE_API_KEY` and `NACE_BASE_URL=https://nace.customer.example` in the process using the CLI or MCP server; no login or profile is required. Environment values take precedence over saved configuration. Alternatively, `nace login --base-url https://nace.customer.example --api-key - < key.txt` validates and saves the key and actual server URL for both tools. For unattended profile use, mount a mode-0600 file and set `NACE_CONFIG_PATH` to it.

{nace_cli-0.3.0 → nace_cli-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.3.0"
+version = "0.4.1"
 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.3.0,<1",
+    "nace-sdk>=0.6.2,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.3.0 → nace_cli-0.4.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "nace-cli"
-version = "0.3.0"
+version = "0.4.1"
 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.3.0,<1",
+    "nace-sdk>=0.6.2,<1",
     "truststore>=0.10.4,<1",
 ]
 

{nace_cli-0.3.0 → nace_cli-0.4.1}/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.3.0"
+__version__ = "0.4.1"

{nace_cli-0.3.0 → nace_cli-0.4.1}/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 _browser, _decide, _docops, _domains, _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
 
@@ -109,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.",
 }
 
 
@@ -152,7 +157,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="nace",
         description=(
-            "Nace CLI: calibrated decisions, document jobs, workspaces, search and browser runs. 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."
         ),
@@ -176,6 +181,7 @@ def build_parser() -> argparse.ArgumentParser:
     _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.3.0 → nace_cli-0.4.1}/src/nace_cli/_inputs.py

@@ -26,6 +26,7 @@ STDIN_FLAGS = {
     "output_schema": "--output-schema",
     "clarification_answers": "--clarification-answers",
     "answer_schema": "--answer-schema",
+    "client_secret_file": "--client-secret-file",
 }
 
 

nace_cli-0.4.1/src/nace_cli/_storage.py

@@ -0,0 +1,342 @@
+"""Storage connections: your own S3 bucket or Azure Blob container a new workspace can keep its files in.
+
+``nace storage`` takes an action: ``list`` and ``get`` read connections; ``create`` makes a draft;
+``setup`` prints what to create in your cloud (saving the setup inputs it is given first);
+``credentials`` saves the role or service principal; ``validate`` checks Nace can use it, and ``--wait``
+waits for the check; ``revoke`` and ``delete`` end it. Every input is a flag. ``nace workspace-create
+--storage ID`` binds a new workspace to a ready one.
+
+The Azure client secret is read from ``--client-secret-file`` (a path, or ``-`` for stdin) or
+``$AZURE_CLIENT_SECRET``, never from a flag's value, and is never printed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+from nace_sdk import (
+    AwsRoleCredential,
+    AzureBlobDestination,
+    AzureServicePrincipalCredential,
+    AzureSetupOptions,
+    DocumentJob,
+    NaceClient,
+    S3Destination,
+    S3SetupOptions,
+    StorageConnection,
+    StorageConnectionSetup,
+)
+from nace_sdk._core.endpoints import DEFAULT_STORAGE_VALIDATION_WAIT_SECONDS, STORAGE_CONNECTION_MAX_PAGE_SIZE
+
+from nace_cli._inputs import read_secret
+from nace_cli._output import CommandFailed, job_json, job_line
+from nace_cli._schemas import _add_page_args
+from nace_cli._workspaces import _emit_listing
+
+#: The two kinds of destination, for ``nace storage create --provider``.
+PROVIDERS = ("s3", "azure_blob")
+#: Where the Azure client secret comes from when ``--client-secret-file`` isn't given.
+AZURE_SECRET_ENV = "AZURE_CLIENT_SECRET"
+#: Each provider's ``nace storage create`` flags, by argparse dest and flag.
+DESTINATION_FLAGS = {"s3": {"bucket": "--bucket", "region": "--region"}, "azure_blob": {"account": "--account", "container": "--container"}}
+#: Each provider's ``nace storage setup`` flags, by setup option and flag.
+SETUP_FLAGS = {
+    "s3": {"access_method": "--access-method", "aws_account_id": "--aws-account-id", "role_name": "--role-name", "kms_key_arn": "--kms-key-arn"},
+    "azure_blob": {
+        "subscription_id": "--subscription-id",
+        "resource_group": "--resource-group",
+        "tenant_id": "--tenant-id",
+        "client_id": "--client-id",
+    },
+}
+#: The setup's one-line values, then its multi-line ones, in the order ``nace storage setup`` prints them.
+SETUP_LINES = (("role_arn", "role arn"), ("launch_url", "launch url"))
+SETUP_BLOCKS = (
+    ("trust_policy", "trust policy"),
+    ("permissions_policy", "permissions policy"),
+    ("cloudformation_template", "cloudformation template"),
+    ("azure_cli", "azure cli"),
+)
+
+
+def _add_id(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--id", dest="connection_id", required=True, metavar="CONNECTION_ID", help="The connection's id, as `nace storage list` lists it."
+    )
+
+
+def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
+    storage = sub.add_parser("storage", help="Connect your own S3 bucket or Azure Blob container for new workspaces.")
+    names = "{list,get,create,setup,credentials,validate,revoke,delete}"
+    actions = storage.add_subparsers(dest="storage_action", metavar=names, required=True)
+
+    listing = actions.add_parser("list", parents=[common], help="List your account's storage connections.")
+    _add_page_args(listing, "Connections", default=50, maximum=STORAGE_CONNECTION_MAX_PAGE_SIZE)
+    listing.set_defaults(run=run_list, family="client")
+
+    show = actions.add_parser("get", parents=[common], help="Print a storage connection and its state.")
+    _add_id(show)
+    show.set_defaults(run=run_get, family="client")
+
+    create = actions.add_parser("create", parents=[common], help="Create a draft connection to a bucket or container you own.")
+    create.add_argument("--name", required=True, metavar="NAME", help="The name people see, 1 to 200 characters.")
+    create.add_argument("--provider", required=True, choices=PROVIDERS, help="An S3 bucket, or an Azure Blob container.")
+    create.add_argument("--bucket", default=None, metavar="BUCKET", help="s3: your bucket.")
+    create.add_argument("--region", default=None, metavar="REGION", help="s3: the bucket's AWS region, such as us-east-1.")
+    create.add_argument("--account", default=None, metavar="ACCOUNT", help="azure_blob: the storage account name.")
+    create.add_argument("--container", default=None, metavar="CONTAINER", help="azure_blob: your container.")
+    create.add_argument("--prefix", default=None, metavar="PREFIX", help="A base prefix inside it; each workspace gets its own folder beneath.")
+    create.set_defaults(run=run_create, family="client")
+
+    setup = actions.add_parser("setup", parents=[common], help="Print what to create in your cloud; save the setup inputs given first.")
+    _add_id(setup)
+    setup.add_argument(
+        "--access-method", default=None, choices=("auto", "manual"), help="s3: auto for the CloudFormation stack, manual to write the role yourself."
+    )
+    setup.add_argument("--aws-account-id", default=None, metavar="ACCOUNT_ID", help="s3: the 12-digit AWS account the role is created in.")
+    setup.add_argument("--role-name", default=None, metavar="NAME", help="s3: the name of the role the stack creates.")
+    setup.add_argument("--kms-key-arn", default=None, metavar="ARN", help="s3: a KMS key the role may use.")
+    setup.add_argument("--subscription-id", default=None, metavar="ID", help="azure_blob: the subscription the storage account is in.")
+    setup.add_argument("--resource-group", default=None, metavar="NAME", help="azure_blob: the resource group the storage account is in.")
+    setup.add_argument("--tenant-id", default=None, metavar="ID", help="azure_blob: your Microsoft Entra tenant.")
+    setup.add_argument("--client-id", default=None, metavar="ID", help="azure_blob: the application (client) id to give access to.")
+    setup.set_defaults(run=run_setup, family="client")
+
+    credentials = actions.add_parser("credentials", parents=[common], help="Save the IAM role, or the Azure service principal, Nace uses.")
+    _add_id(credentials)
+    credentials.add_argument(
+        "--role-arn", default=None, metavar="ARN", help="s3: your IAM role that trusts Nace's roles with the connection's external id."
+    )
+    credentials.add_argument("--tenant-id", default=None, metavar="ID", help="azure_blob: your Microsoft Entra tenant.")
+    credentials.add_argument("--client-id", default=None, metavar="ID", help="azure_blob: the application (client) id.")
+    credentials.add_argument(
+        "--client-secret-file",
+        default=None,
+        metavar="FILE",
+        help=f"azure_blob: a file holding the application's secret, or - for stdin (hidden at a terminal). Default: ${AZURE_SECRET_ENV}.",
+    )
+    credentials.set_defaults(run=run_credentials, family="client")
+
+    validate = actions.add_parser("validate", parents=[common], help="Check that Nace can write, read and delete in the destination.")
+    _add_id(validate)
+    validate.add_argument("--reactivate", action="store_true", help="Restore a connection you revoked once the validation passes.")
+    validate.add_argument("--wait", action="store_true", help="Wait until the validation finishes; exit 1 if it failed.")
+    validate.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=DEFAULT_STORAGE_VALIDATION_WAIT_SECONDS,
+        metavar="SECONDS",
+        help=f"With --wait, how long to wait (default {DEFAULT_STORAGE_VALIDATION_WAIT_SECONDS:.0f}s). It keeps going server-side after.",
+    )
+    validate.set_defaults(run=run_validate, family="client")
+
+    revoke = actions.add_parser("revoke", parents=[common], help="Stop Nace using a connection until it is validated again with --reactivate.")
+    _add_id(revoke)
+    revoke.set_defaults(run=run_revoke, family="client")
+
+    delete = actions.add_parser("delete", parents=[common], help="Delete a connection no workspace uses. Nothing in the bucket is touched.")
+    _add_id(delete)
+    delete.set_defaults(run=run_delete, family="client")
+
+
+# --- Rendering ----------------------------------------------------------------------------------
+
+
+def _where(item: StorageConnection) -> str:
+    destination = item.destination
+    s3 = isinstance(destination, S3Destination)
+    place = f"s3://{destination.bucket}" if s3 else f"azure://{destination.account}/{destination.container}"
+    return f"{place}/{destination.prefix}" if destination.prefix else place
+
+
+def _connection_line(item: StorageConnection) -> str:
+    return f"{item.id}  {item.status}  {_where(item)}  {item.name}"
+
+
+def _connection_detail(item: StorageConnection) -> str:
+    """The connection's line, then what a person setting it up or binding it needs, one fact per line."""
+    lines = [_connection_line(item), f"external id: {item.external_id}"]
+    lines += [f"trusted role: {arn}" for arn in item.aws_trusted_principal_arns]
+    flags = {
+        "credentials pending": item.credentials_pending,
+        "validation running": item.validation_running,
+        "reactivation requires approval": item.reactivation_requires_approval,
+    }
+    lines += [flag for flag, on in flags.items() if on]
+    if item.validated_at:
+        lines.append(f"validated at: {item.validated_at}")
+    if item.revoked_at:
+        lines.append(f"revoked at: {item.revoked_at}" + (f" ({item.revoked_reason})" if item.revoked_reason else ""))
+    lines.append(f"ready for a workspace: {'yes' if item.is_ready else 'no'}")
+    return "\n".join(lines)
+
+
+def _readable(text: str) -> str:
+    """A policy or template as indented JSON; anything else as it came."""
+    try:
+        return json.dumps(json.loads(text), indent=2)
+    except ValueError:
+        return text.rstrip("\n")
+
+
+def _setup_text(setup: StorageConnectionSetup) -> str:
+    options = setup.options.model_dump(mode="json", exclude_none=True)
+    shown = "  ".join(f"{key}={value}" for key, value in options.items() if key != "type")
+    lines = [f"options: {options['type']}" + (f"  {shown}" if shown else "")]
+    lines += [f"{label}: {value}" for field, label in SETUP_LINES if (value := getattr(setup, field))]
+    for field, label in SETUP_BLOCKS:
+        if value := getattr(setup, field):
+            lines += ["", f"{label}:", _readable(value)]
+    return "\n".join(lines)
+
+
+def _emit_connection(item: StorageConnection, args: argparse.Namespace) -> int:
+    print(item.model_dump_json(indent=2, exclude_none=True) if args.json else _connection_line(item))
+    return 0
+
+
+def _connection_id(args: argparse.Namespace) -> str:
+    value = args.connection_id.strip()
+    if not value:
+        raise ValueError("--id must name a storage connection id")
+    return value
+
+
+# --- Commands -----------------------------------------------------------------------------------
+
+
+def run_list(client: NaceClient, args: argparse.Namespace) -> int:
+    connections = client.storage_connections
+    return _emit_listing(
+        args,
+        "storage connections",
+        lambda: connections.list(limit=args.limit, cursor=args.cursor),
+        lambda: connections.iter(),
+        line=_connection_line,
+        extra=lambda page, items: {},
+    )
+
+
+def run_get(client: NaceClient, args: argparse.Namespace) -> int:
+    item = client.storage_connections.get(_connection_id(args))
+    print(item.model_dump_json(indent=2, exclude_none=True) if args.json else _connection_detail(item))
+    return 0
+
+
+def _destination(args: argparse.Namespace) -> S3Destination | AzureBlobDestination:
+    """The destination the flags name: each of the provider's own flags, and none of the other's."""
+    wanted = DESTINATION_FLAGS[args.provider]
+    other = next(flags for provider, flags in DESTINATION_FLAGS.items() if provider != args.provider)
+    missing = [flag for dest, flag in wanted.items() if not (getattr(args, dest) or "").strip()]
+    if missing:
+        raise ValueError(f"--provider {args.provider} needs {' and '.join(missing)}")
+    stray = [flag for dest, flag in other.items() if getattr(args, dest) is not None]
+    if stray:
+        raise ValueError(f"{' and '.join(stray)} {'is' if len(stray) == 1 else 'are'} not for --provider {args.provider}")
+    fields: dict[str, Any] = {dest: getattr(args, dest).strip() for dest in wanted}
+    if args.prefix is not None:
+        fields["prefix"] = args.prefix.strip().strip("/")
+    return S3Destination(**fields) if args.provider == "s3" else AzureBlobDestination(**fields)
+
+
+def run_create(client: NaceClient, args: argparse.Namespace) -> int:
+    name = args.name.strip()
+    if not name or len(name) > 200:
+        raise ValueError("--name must be 1 to 200 characters, not blank")
+    item = client.storage_connections.create(name=name, destination=_destination(args))
+    print(f"next: nace storage setup --id {item.id}", file=sys.stderr)
+    return _emit_connection(item, args)
+
+
+def run_setup(client: NaceClient, args: argparse.Namespace) -> int:
+    """Read the setup; with option flags, save them over the saved options first (the rest keep their values)."""
+    connections = client.storage_connections
+    connection_id = _connection_id(args)
+    given = {option: value for flags in SETUP_FLAGS.values() for option, flag in flags.items() if (value := getattr(args, option)) is not None}
+    setup = connections.setup(connection_id)
+    if given:
+        kind = setup.options.type
+        stray = [flag for provider, flags in SETUP_FLAGS.items() if provider != kind for option, flag in flags.items() if option in given]
+        if stray:
+            # `--tenant-id` and `--client-id` are Azure's; the others name one provider each.
+            raise ValueError(f"{' and '.join(stray)} {'is' if len(stray) == 1 else 'are'} not for a {kind} connection")
+        saved = {option: value for option in SETUP_FLAGS[kind] if (value := getattr(setup.options, option, None)) is not None}
+        merged = {**saved, **given}
+        options = S3SetupOptions(**merged) if kind == "s3" else AzureSetupOptions(**merged)
+        setup = connections.set_setup(connection_id, options)
+    print(setup.model_dump_json(indent=2, exclude_none=True) if args.json else _setup_text(setup))
+    return 0
+
+
+def _azure_secret(args: argparse.Namespace) -> str:
+    if args.client_secret_file is not None:
+        source = args.client_secret_file
+        secret = read_secret(source if source == "-" else f"@{source}", prompt="Azure client secret: ")
+        where = "--client-secret-file"
+    else:
+        secret = os.environ.get(AZURE_SECRET_ENV, "")
+        where = f"${AZURE_SECRET_ENV}"
+        if not secret.strip():
+            raise ValueError(f"the Azure client secret comes from --client-secret-file FILE (- for stdin) or ${AZURE_SECRET_ENV}")
+    if not secret.strip():
+        raise ValueError(f"{where} is empty")
+    return secret
+
+
+def run_credentials(client: NaceClient, args: argparse.Namespace) -> int:
+    azure = {"--tenant-id": args.tenant_id, "--client-id": args.client_id, "--client-secret-file": args.client_secret_file}
+    if args.role_arn is not None:
+        stray = [flag for flag, value in azure.items() if value is not None]
+        if stray:
+            raise ValueError(f"--role-arn is for an S3 connection, and {' and '.join(stray)} for an Azure one: pass one kind")
+        if not args.role_arn.strip():
+            raise ValueError("--role-arn must not be blank")
+        credential: AwsRoleCredential | AzureServicePrincipalCredential = AwsRoleCredential(role_arn=args.role_arn.strip())
+    elif args.tenant_id is not None or args.client_id is not None:
+        missing = [flag for flag in ("--tenant-id", "--client-id") if not (azure[flag] or "").strip()]
+        if missing:
+            raise ValueError(f"an Azure service principal needs {' and '.join(missing)}")
+        credential = AzureServicePrincipalCredential.model_validate(
+            {"tenant_id": args.tenant_id.strip(), "client_id": args.client_id.strip(), "client_secret": _azure_secret(args)}
+        )
+    else:
+        raise ValueError("pass --role-arn for an S3 connection, or --tenant-id and --client-id for an Azure one")
+    item = client.storage_connections.set_credentials(_connection_id(args), credential)
+    print(f"saved; next: nace storage validate --id {item.id} --wait", file=sys.stderr)
+    return _emit_connection(item, args)
+
+
+def _failure(job: DocumentJob) -> str:
+    detail = job.error_message or job.error_code or "no error detail"
+    return f"validation {job.status}: {detail}"
+
+
+def run_validate(client: NaceClient, args: argparse.Namespace) -> int:
+    """Start a validation; with ``--wait``, wait for it and exit ``1`` unless it succeeded."""
+    if not args.wait_timeout >= 0:
+        raise ValueError("--wait-timeout must be 0 or more seconds")
+    connections = client.storage_connections
+    connection_id = _connection_id(args)
+    job = connections.validate(connection_id, reactivate=True if args.reactivate else None)
+    if args.wait:
+        print(job_line(job), file=sys.stderr)
+        job = connections.wait_for_validation(connection_id, timeout=args.wait_timeout)
+    print(job_json(job) if args.json else job_line(job))
+    if args.wait and job.status != "succeeded":
+        raise CommandFailed(_failure(job))
+    return 0
+
+
+def run_revoke(client: NaceClient, args: argparse.Namespace) -> int:
+    return _emit_connection(client.storage_connections.revoke(_connection_id(args)), args)
+
+
+def run_delete(client: NaceClient, args: argparse.Namespace) -> int:
+    connection_id = _connection_id(args)
+    client.storage_connections.delete(connection_id)
+    print(f"deleted {connection_id}", file=sys.stderr)
+    return 0

{nace_cli-0.3.0 → nace_cli-0.4.1}/src/nace_cli/_workspaces.py

@@ -106,6 +106,12 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     create.add_argument(
         "--access", default=None, metavar="JSON", help='Access labels, {"labels": [...], "default_label": ...}: inline JSON, @FILE, a path, or -.'
     )
+    create.add_argument(
+        "--storage",
+        default=None,
+        metavar="CONNECTION_ID",
+        help="Keep the files in this ready storage connection of your account's (`nace storage list`). It can't be changed later.",
+    )
     create.set_defaults(run=run_create, family="client")
 
     delete = sub.add_parser("workspace-delete", parents=[common], help="Delete a workspace and everything in it. It can't be undone.")
@@ -233,6 +239,7 @@ def _emit_listing(
     """One page (or with ``--all`` every item), as the ndi CLI listed it: ``<what> (<total>):``, a line per item, ``next: <cursor>``.
 
     ``--json`` prints ``{"items", "next_cursor", ...extra}``; ``extra`` gets the page read (``None`` with ``--all``) and the items.
+    Without a ``total_count`` from ``extra``, the heading counts the items listed.
     """
     listed = None
     if args.all:
@@ -245,7 +252,7 @@ def _emit_listing(
         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, **fields}))
         return 0
-    print(f"{what} ({fields['total_count']}):")
+    print(f"{what} ({fields.get('total_count', len(items))}):")
     for item in items:
         print(f"  {line(item)}")
     if next_cursor:
@@ -323,7 +330,10 @@ def run_create(client: NaceClient, args: argparse.Namespace) -> int:
     if not name.strip() or len(name) > 120:
         raise ValueError("NAME must be 1 to 120 characters, not blank")
     access = _json_object(args.access, "--access")
-    item = client.workspaces.create(name=name, domain_slug=args.domain, access=access)
+    storage = args.storage.strip() if args.storage is not None else None
+    if storage == "":
+        raise ValueError("--storage must name a storage connection id")
+    item = client.workspaces.create(name=name, domain_slug=args.domain, access=access, storage_connection_id=storage)
     return _emit_workspace(item, args, _name_line(item))