valdtech-cli 0.1.0__py3-none-any.whl

valdtech_cli/cli.py

@@ -0,0 +1,738 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+import hashlib
+import ipaddress
+import json
+import os
+from pathlib import Path
+import stat
+import sys
+import tempfile
+from typing import Any
+from urllib.parse import urlsplit
+import uuid
+
+from . import __version__
+from .auth import device_login, workload_login
+from .config import ConfigStore, Context, build_context
+from .errors import CliError, ExitCode
+from .http import HttpClient, redact
+from .output import emit, emit_error
+
+
+PROVISIONING_PATH = "api/provisioning/v1"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    command = getattr(args, "command", "valdtechctl")
+    try:
+        outcome = _run(args)
+        result, raw_text = outcome[:2]
+        exit_code = outcome[2] if len(outcome) == 3 else ExitCode.SUCCESS
+        emit(command, result, args.output, raw_text=raw_text)
+        return int(exit_code)
+    except CliError as error:
+        emit_error(command, error.code, error.message, error.details, args.output)
+        return int(error.exit_code)
+    except KeyboardInterrupt:
+        emit_error(command, "cancelled", "The operation was cancelled.", None, args.output)
+        return int(ExitCode.CANCELLED)
+
+
+def _run(
+    args: argparse.Namespace,
+) -> tuple[Any, str | None] | tuple[Any, str | None, ExitCode]:
+    store = ConfigStore()
+    if args.command == "bootstrap":
+        return _bootstrap(args), None
+    if args.command == "context":
+        return _context(args, store), None
+    context = _effective_context(store.current_context(args.context), args.api_url)
+    if args.command == "login":
+        if args.workload_private_key:
+            password = os.environ.get(args.private_key_password_env) if args.private_key_password_env else None
+            result = workload_login(
+                context,
+                store,
+                args.timeout,
+                args.workload_private_key,
+                args.key_id,
+                password,
+            )
+            return {
+                "context": context.name,
+                "authentication": "private_key_jwt",
+                "expiresAt": result.token.expires_at.isoformat(),
+                "scope": result.granted_scope,
+            }, None
+        if args.non_interactive:
+            raise CliError("Device login requires an interactive user.", ExitCode.AUTHENTICATION, "interactive-login-required")
+        result = device_login(context, store, args.timeout, open_browser=args.open_browser)
+        return {
+            "context": context.name,
+            "expiresAt": result.token.expires_at.isoformat(),
+            "scope": result.granted_scope,
+        }, None
+
+    token = store.load_token(context.name)
+    access_token = token.value if token and not token.expired else None
+    client = HttpClient(context.api_url, args.timeout, access_token)
+    if args.command == "validate":
+        manifest, manifest_format = _manifest(args.file, args.manifest_format)
+        response = client.post_json(
+            f"{PROVISIONING_PATH}/validate",
+            {"manifest": manifest, "format": manifest_format},
+        ).json()
+        if not isinstance(response, dict) or response.get("isValid") is not True:
+            diagnostics = response.get("diagnostics") if isinstance(response, dict) else None
+            raise CliError("The manifest is invalid.", ExitCode.VALIDATION, "manifest-invalid", diagnostics)
+        return response, None
+    if args.command == "plan":
+        manifest, manifest_format = _manifest(args.file, args.manifest_format)
+        response = _plan(client, manifest, manifest_format, _inputs(args))
+        _raise_for_plan_status(response)
+        return response, None
+    if args.command == "drift":
+        return _drift(args, client)
+    if args.command == "apply":
+        return _apply(args, client), None
+    if args.command == "operation":
+        if args.operation_command == "resume":
+            result = _resume_operation(args, client)
+            exit_code = (
+                ExitCode.PARTIAL_EXTERNAL_EFFECT
+                if result.get("status") == 1
+                else ExitCode.SUCCESS
+            )
+            return result, None, exit_code
+        return _get_operation(args, client), None
+    if args.command == "export":
+        return _export_configuration(args, client)
+    if args.command == "schema":
+        response = client.get(f"{PROVISIONING_PATH}/schema")
+        try:
+            schema_text = response.body.decode("utf-8")
+            schema = json.loads(schema_text)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise CliError("The server returned an invalid schema.", ExitCode.SERVER_FAILURE, "invalid-schema") from error
+        digest = hashlib.sha256(response.body).hexdigest()
+        if args.file:
+            _write_new_or_replace(Path(args.file), response.body)
+        result = {
+            "apiVersion": _schema_api_version(schema),
+            "sha256": digest,
+            "mediaType": response.content_type,
+            "file": str(Path(args.file).resolve()) if args.file else None,
+            "schema": None if args.file else schema,
+        }
+        return result, schema_text if args.output == "text" and not args.file else None
+    if args.command == "doctor":
+        result = _doctor(context, token, client)
+        if not result["healthy"]:
+            exit_code = ExitCode.AUTHENTICATION if not result["checks"][1]["ok"] else ExitCode.SERVER_FAILURE
+            raise CliError("One or more doctor checks failed.", exit_code, "doctor-unhealthy", result)
+        return result, None
+    raise CliError("Unknown command.", ExitCode.USAGE, "unknown-command")
+
+
+def _bootstrap(args: argparse.Namespace) -> dict[str, Any]:
+    api_url = args.api_url.rstrip("/")
+    parsed = urlsplit(api_url)
+    try:
+        loopback = parsed.hostname == "localhost" or (
+            parsed.hostname is not None and ipaddress.ip_address(parsed.hostname).is_loopback
+        )
+    except ValueError:
+        loopback = False
+    if parsed.scheme not in {"http", "https"} or not loopback or parsed.username or parsed.password:
+        raise CliError(
+            "Bootstrap requires an explicit loopback API URL. Remote bootstrap requires an operator-managed mTLS client.",
+            ExitCode.VALIDATION,
+            "bootstrap-loopback-required",
+        )
+
+    token_path = Path(args.token_file)
+    try:
+        file_status = token_path.lstat()
+        if not stat.S_ISREG(file_status.st_mode) or token_path.is_symlink():
+            raise OSError("not a regular file")
+        if os.name != "nt" and stat.S_IMODE(file_status.st_mode) & 0o077:
+            raise OSError("permissions are not owner-only")
+        token = token_path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError) as error:
+        raise CliError(
+            "The bootstrap token must be a readable regular file accessible only to its owner.",
+            ExitCode.VALIDATION,
+            "unsafe-bootstrap-token-file",
+        ) from error
+    if len(token) < 32 or len(token) > 512:
+        raise CliError(
+            "The bootstrap token file has an invalid value.",
+            ExitCode.VALIDATION,
+            "invalid-bootstrap-token",
+        )
+
+    client = HttpClient(api_url, args.timeout)
+    response = client.post_json(
+        f"{PROVISIONING_PATH}/bootstrap",
+        {
+            "tenantKey": args.tenant_key,
+            "displayName": args.display_name,
+            "administratorIdentifier": args.administrator,
+        },
+        headers={"X-Valdtech-Bootstrap-Token": token},
+        authenticated=False,
+        sensitive_values=(token,),
+    ).json()
+    if not isinstance(response, dict) or response.get("status") != 0:
+        raise CliError(
+            "The bootstrap ceremony did not complete.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-bootstrap-response",
+        )
+    return {
+        "status": response["status"],
+        "tenantKey": args.tenant_key,
+        "administratorIdentifier": args.administrator,
+    }
+
+
+def _context(args: argparse.Namespace, store: ConfigStore) -> Any:
+    if args.context_command == "use":
+        provided = any((args.api_url, args.issuer, args.client_id, args.scope))
+        context = None
+        if provided:
+            if not all((args.api_url, args.issuer, args.client_id, args.scope)):
+                raise CliError(
+                    "A new context requires --api-url, --issuer, --client-id, and --scope.",
+                    ExitCode.VALIDATION,
+                    "incomplete-context",
+                )
+            context = build_context(args.name, args.api_url, args.issuer, args.client_id, args.scope)
+        return store.use_context(context, args.name).public_dict()
+    if args.context_command == "show":
+        return store.current_context(args.name).public_dict()
+    current, contexts = store.list_contexts()
+    return {"currentContext": current, "contexts": [item.public_dict() for item in contexts]}
+
+
+def _apply(args: argparse.Namespace, client: HttpClient) -> Any:
+    non_secret_inputs = _inputs(args)
+    plan: dict[str, Any] | None = None
+    if args.plan_id:
+        try:
+            plan_id = str(uuid.UUID(args.plan_id))
+        except (ValueError, AttributeError) as error:
+            raise CliError("--plan-id must be a valid UUID.", ExitCode.VALIDATION, "invalid-plan-id") from error
+        approval = plan_id
+    else:
+        manifest, manifest_format = _manifest(args.file, args.manifest_format)
+        plan = _plan(client, manifest, manifest_format, non_secret_inputs)
+        _raise_for_plan_status(plan)
+        plan_id = _required_response_string(plan, "planId")
+        approval = _required_response_string(plan, "planDigest")
+        print(_plan_summary(plan), file=sys.stderr)
+
+    if args.non_interactive:
+        if args.approve != approval:
+            raise CliError(
+                "Non-interactive apply requires --approve with the exact reviewed plan digest or plan id.",
+                ExitCode.VALIDATION,
+                "approval-required",
+            )
+    elif args.approve != approval:
+        answer = input(f"Apply reviewed plan {approval}? [y/N] ")
+        if answer.strip().lower() not in {"y", "yes"}:
+            raise CliError("Apply was not confirmed.", ExitCode.CANCELLED, "apply-not-confirmed")
+
+    secret_inputs = _secret_inputs(args)
+    required = {
+        item["key"]
+        for item in (plan or {}).get("requiredSecretInputs", [])
+        if isinstance(item, dict) and isinstance(item.get("key"), str)
+    }
+    if plan is not None and set(secret_inputs) != required:
+        missing = sorted(required - set(secret_inputs))
+        unexpected = sorted(set(secret_inputs) - required)
+        raise CliError(
+            "Secret inputs do not match the reviewed plan.",
+            ExitCode.VALIDATION,
+            "secret-input-mismatch",
+            {"missingKeys": missing, "unexpectedKeys": unexpected},
+        )
+    idempotency_key = args.idempotency_key or str(uuid.uuid4())
+    sensitive_values = tuple(secret_inputs.values())
+    response = client.post_json(
+        f"{PROVISIONING_PATH}/plans/{plan_id}/apply",
+        {"nonSecretInputs": non_secret_inputs, "secretInputs": secret_inputs},
+        headers={"Idempotency-Key": idempotency_key},
+        sensitive_values=sensitive_values,
+    ).json()
+    response = redact(response, sensitive_values)
+    _raise_for_apply_status(response)
+    return {"plan": plan, "operation": response, "idempotencyKey": idempotency_key}
+
+
+def _get_operation(args: argparse.Namespace, client: HttpClient) -> dict[str, Any]:
+    operation_id = _canonical_uuid(args.operation_id, "OPERATION_ID", "invalid-operation-id")
+    response = client.get(f"{PROVISIONING_PATH}/operations/{operation_id}").json()
+    if not isinstance(response, dict) or response.get("status") != 0:
+        raise CliError(
+            "The server returned an invalid operation response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-operation-response",
+        )
+    operation = response.get("operation")
+    if not isinstance(operation, dict):
+        raise CliError(
+            "The server returned an invalid operation response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-operation-response",
+        )
+    returned_id = operation.get("operationId")
+    try:
+        returned_operation_id = str(uuid.UUID(returned_id))
+    except (ValueError, TypeError, AttributeError) as error:
+        raise CliError(
+            "The server returned an invalid operation response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-operation-response",
+        ) from error
+    if returned_operation_id != operation_id:
+        raise CliError(
+            "The server returned a different operation than requested.",
+            ExitCode.SERVER_FAILURE,
+            "operation-response-mismatch",
+        )
+    return response
+
+
+def _resume_operation(args: argparse.Namespace, client: HttpClient) -> dict[str, Any]:
+    operation_id = _canonical_uuid(args.operation_id, "OPERATION_ID", "invalid-operation-id")
+    response = client.post_json(
+        f"{PROVISIONING_PATH}/operations/{operation_id}/resume",
+        {},
+    ).json()
+    if not isinstance(response, dict) or response.get("status") not in {0, 1}:
+        raise CliError(
+            "The server returned an invalid operation-resume response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-operation-resume-response",
+        )
+    returned_id = response.get("operationId")
+    try:
+        returned_operation_id = str(uuid.UUID(returned_id))
+    except (ValueError, TypeError, AttributeError) as error:
+        raise CliError(
+            "The server returned an invalid operation-resume response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-operation-resume-response",
+        ) from error
+    if returned_operation_id != operation_id:
+        raise CliError(
+            "The server resumed a different operation than requested.",
+            ExitCode.SERVER_FAILURE,
+            "operation-resume-response-mismatch",
+        )
+    for field in ("completedEffects", "pendingEffects"):
+        if not isinstance(response.get(field), int) or response[field] < 0:
+            raise CliError(
+                "The server returned an invalid operation-resume response.",
+                ExitCode.SERVER_FAILURE,
+                "invalid-operation-resume-response",
+            )
+    return response
+
+
+def _export_configuration(
+    args: argparse.Namespace,
+    client: HttpClient,
+) -> tuple[dict[str, Any], str | None]:
+    response = client.get(f"{PROVISIONING_PATH}/export").json()
+    if not isinstance(response, dict):
+        raise CliError(
+            "The server returned an invalid export response.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-export-response",
+        )
+    _raise_for_export_status(response)
+    envelope = response.get("envelope")
+    if not isinstance(envelope, dict):
+        raise CliError(
+            "The server export response has no manifest envelope.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-export-response",
+        )
+    manifest = envelope.get("manifest")
+    manifest_format = envelope.get("format")
+    if not isinstance(manifest, str) or not manifest or manifest_format not in {0, 1}:
+        raise CliError(
+            "The server export response has an invalid manifest envelope.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-export-response",
+        )
+
+    if args.file:
+        destination = Path(args.file)
+        _write_new_or_replace(destination, manifest.encode("utf-8"))
+        result = {
+            "status": response.get("status"),
+            "manifestDigest": response.get("manifestDigest"),
+            "omittedWriteOnlyPaths": response.get("omittedWriteOnlyPaths"),
+            "diagnostics": response.get("diagnostics"),
+            "format": manifest_format,
+            "file": str(destination.resolve()),
+        }
+        return result, None
+    return response, manifest if args.output == "text" else None
+
+
+def _plan(client: HttpClient, manifest: str, manifest_format: int, inputs: dict[str, str]) -> dict[str, Any]:
+    response = client.post_json(
+        f"{PROVISIONING_PATH}/plans",
+        {"envelope": {"manifest": manifest, "format": manifest_format}, "nonSecretInputs": inputs},
+    ).json()
+    if not isinstance(response, dict):
+        raise CliError("The plan response is invalid.", ExitCode.SERVER_FAILURE, "invalid-plan-response")
+    return response
+
+
+def _drift(
+    args: argparse.Namespace,
+    client: HttpClient,
+) -> tuple[dict[str, Any], None, ExitCode]:
+    manifest, manifest_format = _manifest(args.file, args.manifest_format)
+    response = client.post_json(
+        f"{PROVISIONING_PATH}/drift",
+        {
+            "envelope": {"manifest": manifest, "format": manifest_format},
+            "nonSecretInputs": _inputs(args),
+        },
+    ).json()
+    if not isinstance(response, dict):
+        raise CliError(
+            "The drift response is invalid.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-drift-response",
+        )
+    _raise_for_drift_status(response)
+    has_drift = response.get("hasDrift")
+    if not isinstance(has_drift, bool) or not isinstance(response.get("operations"), list):
+        raise CliError(
+            "The drift response is incomplete.",
+            ExitCode.SERVER_FAILURE,
+            "invalid-drift-response",
+        )
+    return response, None, ExitCode.CONFLICT if has_drift else ExitCode.SUCCESS
+
+
+def _doctor(context: Context, token, client: HttpClient) -> dict[str, Any]:  # noqa: ANN001
+    checks: list[dict[str, Any]] = [
+        {"name": "context", "ok": True, "detail": context.name},
+        {"name": "token", "ok": bool(token and not token.expired), "detail": "available" if token and not token.expired else "missing-or-expired"},
+    ]
+    try:
+        discovery = HttpClient(context.issuer, client.timeout).get(
+            f"{context.issuer}/.well-known/openid-configuration",
+            authenticated=False,
+        ).json()
+        checks.append({"name": "oidc-discovery", "ok": isinstance(discovery, dict), "detail": context.issuer})
+    except CliError as error:
+        checks.append({"name": "oidc-discovery", "ok": False, "detail": error.code})
+    try:
+        schema = client.get(f"{PROVISIONING_PATH}/schema")
+        parsed = json.loads(schema.body.decode("utf-8"))
+        checks.append({"name": "provisioning-api", "ok": isinstance(parsed, dict), "detail": _schema_api_version(parsed)})
+    except (CliError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        checks.append({"name": "provisioning-api", "ok": False, "detail": getattr(error, "code", "invalid-schema")})
+    return {"healthy": all(item["ok"] for item in checks), "checks": checks}
+
+
+def _manifest(filename: str, manifest_format: str | None) -> tuple[str, int]:
+    if filename == "-":
+        raw = sys.stdin.buffer.read()
+        if not manifest_format:
+            raise CliError("--format is required when reading a manifest from stdin.", ExitCode.VALIDATION, "manifest-format-required")
+    else:
+        path = Path(filename)
+        try:
+            raw = path.read_bytes()
+        except OSError as error:
+            raise CliError(f"Manifest '{filename}' could not be read.", ExitCode.VALIDATION, "manifest-read-failed") from error
+        if not manifest_format:
+            suffix = path.suffix.lower()
+            manifest_format = "json" if suffix == ".json" else "yaml" if suffix in {".yaml", ".yml"} else None
+        if not manifest_format:
+            raise CliError("Manifest format could not be inferred; use --format.", ExitCode.VALIDATION, "manifest-format-required")
+    try:
+        return raw.decode("utf-8"), 0 if manifest_format == "json" else 1
+    except UnicodeDecodeError as error:
+        raise CliError("The manifest must be UTF-8.", ExitCode.VALIDATION, "manifest-encoding-invalid") from error
+
+
+def _inputs(args: argparse.Namespace) -> dict[str, str]:
+    result = _pairs(getattr(args, "input", []), "--input")
+    for key, environment_name in _pairs(getattr(args, "input_env", []), "--input-env").items():
+        if environment_name not in os.environ:
+            raise CliError(f"Environment variable '{environment_name}' is missing.", ExitCode.VALIDATION, "input-environment-missing")
+        result[key] = os.environ[environment_name]
+    return result
+
+
+def _secret_inputs(args: argparse.Namespace) -> dict[str, str]:
+    result: dict[str, str] = {}
+    mappings = _pairs(args.secret_env, "--secret-env")
+    for key, environment_name in mappings.items():
+        if environment_name not in os.environ:
+            raise CliError(f"Secret environment variable for key '{key}' is missing.", ExitCode.VALIDATION, "secret-environment-missing")
+        result[key] = os.environ[environment_name]
+    return result
+
+
+def _pairs(values: list[str], option: str) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for value in values:
+        key, separator, item = value.partition("=")
+        if not separator or not key or len(key) > 128 or len(item) > 8192:
+            raise CliError(f"{option} expects bounded KEY=VALUE entries.", ExitCode.VALIDATION, "invalid-input")
+        if key in result:
+            raise CliError(f"Duplicate input key '{key}'.", ExitCode.VALIDATION, "duplicate-input")
+        result[key] = item
+    return result
+
+
+def _raise_for_plan_status(response: dict[str, Any]) -> None:
+    status = response.get("status")
+    if status == 0:
+        return
+    code = ExitCode.AUTHENTICATION if status == 2 else ExitCode.CONFLICT if status == 3 else ExitCode.VALIDATION
+    raise CliError("Provisioning plan was not accepted.", code, "plan-rejected", response.get("diagnostics"))
+
+
+def _raise_for_drift_status(response: dict[str, Any]) -> None:
+    status = response.get("status")
+    if status == 0:
+        return
+    if status == 2:
+        exit_code = ExitCode.AUTHENTICATION
+    elif status == 3:
+        exit_code = ExitCode.CONFLICT
+    elif status == 1:
+        exit_code = ExitCode.VALIDATION
+    else:
+        exit_code = ExitCode.SERVER_FAILURE
+    raise CliError(
+        "Provisioning drift could not be evaluated.",
+        exit_code,
+        "drift-evaluation-rejected",
+        response.get("diagnostics"),
+    )
+
+
+def _raise_for_apply_status(response: Any) -> None:
+    if not isinstance(response, dict):
+        raise CliError("The apply response is invalid.", ExitCode.SERVER_FAILURE, "invalid-apply-response")
+    status = response.get("status")
+    if status == 0:
+        return
+    if status == 4:
+        exit_code = ExitCode.AUTHENTICATION
+    elif status in {2, 3, 5, 6, 7}:
+        exit_code = ExitCode.CONFLICT
+    else:
+        exit_code = ExitCode.VALIDATION
+    raise CliError("Provisioning apply was not accepted.", exit_code, "apply-rejected", response.get("diagnostics"))
+
+
+def _raise_for_export_status(response: dict[str, Any]) -> None:
+    status = response.get("status")
+    if status == 0:
+        return
+    if status == 1:
+        exit_code = ExitCode.AUTHENTICATION
+    elif status == 2:
+        exit_code = ExitCode.VALIDATION
+    else:
+        exit_code = ExitCode.SERVER_FAILURE
+    raise CliError(
+        "Provisioning configuration could not be exported.",
+        exit_code,
+        "export-rejected",
+        response.get("diagnostics"),
+    )
+
+
+def _plan_summary(plan: dict[str, Any]) -> str:
+    operations = plan.get("operations") if isinstance(plan.get("operations"), list) else []
+    required = plan.get("requiredSecretInputs") if isinstance(plan.get("requiredSecretInputs"), list) else []
+    return f"Reviewed plan {plan.get('planDigest')}: {len(operations)} operation(s), {len(required)} secret input(s)."
+
+
+def _required_response_string(value: dict[str, Any], key: str) -> str:
+    item = value.get(key)
+    if not isinstance(item, str) or not item:
+        raise CliError("The server plan response is incomplete.", ExitCode.SERVER_FAILURE, "invalid-plan-response")
+    return item
+
+
+def _canonical_uuid(value: Any, field: str, code: str) -> str:
+    try:
+        return str(uuid.UUID(value))
+    except (ValueError, TypeError, AttributeError) as error:
+        raise CliError(
+            f"{field} must be a valid UUID.",
+            ExitCode.VALIDATION,
+            code,
+        ) from error
+
+
+def _effective_context(context: Context, api_url: str | None) -> Context:
+    if not api_url:
+        return context
+    override = build_context(context.name, api_url, context.issuer, context.client_id, list(context.scopes))
+    return replace(context, api_url=override.api_url)
+
+
+def _schema_api_version(schema: Any) -> str | None:
+    try:
+        value = schema["properties"]["apiVersion"]["const"]
+        return value if isinstance(value, str) else None
+    except (KeyError, TypeError):
+        return None
+
+
+def _write_new_or_replace(path: Path, content: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(content)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            os.unlink(temporary_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="valdtechctl", description="Valdtech Provisioning API client")
+    parser.add_argument("--version", action="version", version=f"valdtechctl {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    login = commands.add_parser("login", help="Authenticate using OAuth Device Authorization")
+    _common_arguments(login)
+    login.add_argument("--open-browser", action="store_true", help="Open the verification URI in the default browser")
+    login.add_argument("--workload-private-key", metavar="PEM_FILE", help="Authenticate a workload with private_key_jwt")
+    login.add_argument("--key-id", help="Registered JWK key id for private_key_jwt")
+    login.add_argument("--private-key-password-env", metavar="ENV_VAR", help="Environment variable containing the PEM password")
+
+    bootstrap = commands.add_parser("bootstrap", help="Run the one-time local instance bootstrap ceremony")
+    _common_arguments(bootstrap, connection=False)
+    bootstrap.add_argument("--api-url", required=True, help="Explicit loopback Administration API URL")
+    bootstrap.add_argument("--token-file", required=True, help="Owner-only file containing the one-time bootstrap token")
+    bootstrap.add_argument("--tenant-key", required=True)
+    bootstrap.add_argument("--display-name", required=True)
+    bootstrap.add_argument("--administrator", required=True, help="Initial administrator email or stable identifier")
+
+    context = commands.add_parser("context", help="Manage named server contexts")
+    context_commands = context.add_subparsers(dest="context_command", required=True)
+    use = context_commands.add_parser("use", help="Create/select a context")
+    _common_arguments(use, connection=False)
+    use.add_argument("name")
+    use.add_argument("--api-url")
+    use.add_argument("--issuer")
+    use.add_argument("--client-id")
+    use.add_argument("--scope", action="append", default=[])
+    show = context_commands.add_parser("show", help="Show a context")
+    _common_arguments(show, connection=False)
+    show.add_argument("name", nargs="?")
+    context_list = context_commands.add_parser("list", help="List contexts")
+    _common_arguments(context_list, connection=False)
+
+    validate = commands.add_parser("validate", help="Validate a manifest on the server")
+    _common_arguments(validate)
+    _manifest_arguments(validate)
+
+    plan = commands.add_parser("plan", help="Create a persisted, secret-free plan")
+    _common_arguments(plan)
+    _manifest_arguments(plan)
+    _input_arguments(plan)
+
+    drift = commands.add_parser("drift", help="Compare a manifest with current observable state without creating a plan")
+    _common_arguments(drift)
+    _manifest_arguments(drift)
+    _input_arguments(drift)
+
+    apply = commands.add_parser("apply", help="Apply a reviewed plan")
+    _common_arguments(apply)
+    source = apply.add_mutually_exclusive_group(required=True)
+    source.add_argument("-f", "--file", help="Manifest file, or '-' for stdin")
+    source.add_argument("--plan-id", help="Existing reviewed plan id")
+    apply.add_argument("--format", dest="manifest_format", choices=("json", "yaml"))
+    _input_arguments(apply)
+    apply.add_argument("--secret-env", action="append", default=[], metavar="KEY=ENV_VAR")
+    apply.add_argument("--approve", help="Exact reviewed plan digest (or plan id with --plan-id)")
+    apply.add_argument("--idempotency-key", help="Stable visible-ASCII retry key")
+
+    operation = commands.add_parser("operation", help="Inspect provisioning operations")
+    operation_commands = operation.add_subparsers(dest="operation_command", required=True)
+    operation_get = operation_commands.add_parser("get", help="Get an operation owned by the current actor and tenant")
+    _common_arguments(operation_get)
+    operation_get.add_argument("operation_id", metavar="OPERATION_ID")
+    operation_resume = operation_commands.add_parser(
+        "resume",
+        help="Retry pending external effects for an operation owned by the current actor and tenant",
+    )
+    _common_arguments(operation_resume)
+    operation_resume.add_argument("operation_id", metavar="OPERATION_ID")
+
+    export = commands.add_parser("export", help="Export authorized configuration without secrets")
+    _common_arguments(export)
+    export.add_argument("-f", "--file", help="Write the server-produced manifest to this file")
+
+    schema = commands.add_parser("schema", help="Download the active server schema")
+    _common_arguments(schema)
+    schema.add_argument("-f", "--file", help="Write the schema to this file")
+    doctor = commands.add_parser("doctor", help="Check context, authentication, discovery, and API compatibility")
+    _common_arguments(doctor)
+    return parser
+
+
+def _common_arguments(parser: argparse.ArgumentParser, *, connection: bool = True) -> None:
+    if connection:
+        parser.add_argument("--context", help="Context name (defaults to the current context)")
+        parser.add_argument("--api-url", help="Temporary API URL override")
+        parser.add_argument("--timeout", type=_positive_timeout, default=30.0, help="HTTP timeout in seconds")
+        parser.add_argument("--non-interactive", action="store_true")
+        parser.add_argument("--wait", action="store_true", help="Wait for a synchronous operation result")
+    else:
+        parser.set_defaults(context=None, api_url=None, timeout=30.0, non_interactive=False, wait=False)
+    parser.add_argument("--output", choices=("text", "json", "yaml"), default="text")
+
+
+def _manifest_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-f", "--file", required=True, help="Manifest file, or '-' for stdin")
+    parser.add_argument("--format", dest="manifest_format", choices=("json", "yaml"))
+
+
+def _input_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--input", action="append", default=[], metavar="KEY=VALUE")
+    parser.add_argument("--input-env", action="append", default=[], metavar="KEY=ENV_VAR")
+
+
+def _positive_timeout(value: str) -> float:
+    try:
+        parsed = float(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("timeout must be a number") from error
+    if parsed <= 0 or parsed > 600:
+        raise argparse.ArgumentTypeError("timeout must be between 0 and 600 seconds")
+    return parsed