fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/cli_parser.py

@@ -0,0 +1,791 @@
+"""Declare the public CLI grammar without loading profiles or selecting a deployment target."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from fdai_service_contracts.product_profile import ObservationDataSource, ProductAddOn
+
+from fdai_deployment_cli import source_change_parser
+from fdai_deployment_cli.__about__ import __version__
+from fdai_deployment_cli.aks_service_update import SERVICES as AKS_SERVICES
+from fdai_deployment_cli.cli_help import (
+    AZURE_DESCRIPTION,
+    AZURE_EPILOG,
+    ROOT_DESCRIPTION,
+    ROOT_EPILOG,
+    HelpParser,
+    command,
+    command_group,
+)
+from fdai_deployment_cli.foundation_plan import register_foundation_plan_command
+from fdai_deployment_cli.lifecycle_configuration_cli import register_configuration_commands
+from fdai_deployment_cli.runtime_profile import DATABASE_SKUS
+from fdai_deployment_cli.state_handoff import register_state_handoff_command
+
+CommandHandler = Callable[[argparse.Namespace], int]
+
+
+def build_parser(handlers: Mapping[str, CommandHandler]) -> argparse.ArgumentParser:
+    """Bind command handlers without calling them; empty groups show only their own help.
+
+    Leaf requirements, types, choices, and mutually exclusive sources remain argparse
+    contracts. Resolving the default work directory belongs to execution, not discovery.
+    """
+
+    parser = HelpParser(prog="fdaictl", description=ROOT_DESCRIPTION, epilog=ROOT_EPILOG)
+    parser.add_argument(
+        "--version", action="version", version=__version__, help="show the CLI version and exit"
+    )
+    subcommands = command_group(parser)
+    register_configuration_commands(subcommands)
+
+    version = command(subcommands, "version", "Show the installed CLI version")
+    version.add_argument("--output", choices=("text", "json"), default="text")
+    version.set_defaults(handler=handlers["version"])
+
+    doctor = command(subcommands, "doctor", "Check local tools and Azure authentication")
+    doctor.add_argument("--output", choices=("text", "json"), default="text")
+    doctor.set_defaults(handler=handlers["doctor"])
+
+    offline = command(
+        subcommands,
+        "offline",
+        "Prepare and verify local signed-kit artifacts",
+        epilog="Next: fdaictl offline prepare --help\nThese operations do not deploy Azure resources.",
+    )
+    offline_commands = command_group(offline)
+    prepare = command(
+        offline_commands, "prepare", "Verify a signed kit and create a private snapshot"
+    )
+    prepare.add_argument("--offline-kit", type=Path, required=True)
+    prepare.add_argument("--release-root", type=Path, required=True)
+    prepare.add_argument("--bundle-public-key", type=Path, required=True)
+    prepare.add_argument("--profile", type=Path, required=True)
+    prepare.add_argument("--source-commit", required=True)
+    prepare.add_argument("--work-dir", type=Path, required=True)
+    prepare.add_argument("--output", choices=("text", "json"), default="text")
+    prepare.set_defaults(handler=handlers["offline_prepare"])
+    configure = command(
+        offline_commands, "configure-console", "Write local Console configuration; do not publish"
+    )
+    configure.add_argument(
+        "--directory",
+        type=Path,
+        required=True,
+        help="Private prebuilt Console directory whose shipped configuration will be replaced",
+    )
+    configure.add_argument("--settings", type=Path, required=True)
+    configure.add_argument("--output", choices=("text", "json"), default="text")
+    configure.set_defaults(handler=handlers["offline_configure_console"])
+    install = command(
+        offline_commands, "install-support", "Install migration support from verified local wheels"
+    )
+    install.add_argument("--offline-kit", type=Path, required=True)
+    install.add_argument("--release-root", type=Path, required=True)
+    install.add_argument("--work-dir", type=Path, required=True)
+    install.add_argument("--output", choices=("text", "json"), default="text")
+    install.set_defaults(handler=handlers["offline_install_support"])
+
+    provision = command(
+        subcommands,
+        "provision",
+        "Prepare deployment inputs or deploy FDAI to Azure",
+        epilog=(
+            "Start here: fdaictl provision azure --help\n"
+            "Advanced profile and verification commands never replace exact approval."
+        ),
+    )
+    provision_commands = command_group(provision)
+    azure = command(
+        provision_commands,
+        "azure",
+        "Prepare source or deploy a signed kit with exact approvals",
+        description=AZURE_DESCRIPTION,
+        epilog=AZURE_EPILOG,
+    )
+    source_options = azure.add_argument_group("Artifact source (choose one)")
+    kit_source = source_options.add_mutually_exclusive_group(required=True)
+    kit_source.add_argument(
+        "--offline-kit",
+        type=Path,
+        metavar="PATH",
+        help="Use a local signed kit; no public artifact fallback",
+    )
+    kit_source.add_argument(
+        "--source",
+        type=Path,
+        metavar="PATH",
+        help="Select a clean source checkout for connected dev AKS deployment",
+    )
+    kit_source.add_argument(
+        "--hub",
+        type=Path,
+        metavar="PATH",
+        help="Select a clean checkout and import signed Release Hub images; never build services",
+    )
+    source_options.add_argument("--hub-url", help="Public HTTPS Release Hub origin")
+    source_options.add_argument(
+        "--hub-public-key",
+        type=Path,
+        help="Independently provisioned Ed25519 public PEM (or FDAI_HUB_PUBLIC_KEY path)",
+    )
+    source_options.add_argument(
+        "--hub-release", help="Exact signed Release in the selected channel"
+    )
+    source_options.add_argument("--hub-channel", help="Release channel (default: RELEASE)")
+    source_action = azure.add_mutually_exclusive_group()
+    source_action.add_argument(
+        "--prepare-only",
+        action="store_true",
+        help="Verify source and retain a private snapshot without Azure access (source mode only)",
+    )
+    source_action.add_argument(
+        "--preflight-only",
+        action="store_true",
+        help="Prepare source and read AKS SKU/quota feasibility without Azure mutation",
+    )
+    source_action.add_argument(
+        "--teardown",
+        action="store_true",
+        help="Remove only resources proven to belong to the retained source installation",
+    )
+    azure.add_argument(
+        "--teardown-confirmation",
+        metavar="TEXT",
+        help="Typed confirmation printed by --teardown review; performs the deletion",
+    )
+    azure.add_argument(
+        "--approval-file",
+        type=Path,
+        metavar="PATH",
+        help="Existing exact human checkpoint approval (source mode only); never prompt",
+    )
+    azure.add_argument(
+        "--foundation-recovery-directory",
+        type=Path,
+        metavar="PATH",
+        help="Resume an existing source run after separately verified Foundation recovery",
+    )
+    settings = azure.add_argument_group("Deployment settings")
+    settings.add_argument(
+        "--region", default="koreacentral", help="Azure deployment region (default: %(default)s)"
+    )
+    settings.add_argument(
+        "--runtime",
+        choices=("container-apps", "aks"),
+        default="aks",
+        help="Runtime platform for a new installation (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--database",
+        choices=("postgres-flex", "postgres-aks"),
+        default="postgres-flex",
+        metavar="PLACEMENT",
+        help="PostgreSQL placement for a new installation (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--system-nodes",
+        type=int,
+        default=3,
+        metavar="COUNT",
+        help="AKS system node count; minimum 2 (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--system-node-sku",
+        default=None,
+        metavar="SKU",
+        help="AKS system node VM SKU (AKS default: Standard_D4ds_v4)",
+    )
+    settings.add_argument(
+        "--user-nodes",
+        type=int,
+        default=3,
+        metavar="COUNT",
+        help="AKS user node minimum; postgres-aks requires 4 (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--max-user-nodes",
+        type=int,
+        default=5,
+        metavar="COUNT",
+        help="AKS user node autoscaler maximum (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--user-node-sku",
+        default="Standard_D4ds_v4",
+        metavar="SKU",
+        help="AKS user node VM SKU (default: %(default)s)",
+    )
+    settings.add_argument(
+        "--database-sku",
+        default=None,
+        choices=DATABASE_SKUS,
+        metavar="SKU",
+        help="PostgreSQL Flexible Server SKU for postgres-flex (default: GP_Standard_D4ads_v5)",
+    )
+    settings.add_argument(
+        "--monthly-cost-ceiling",
+        type=int,
+        default=None,
+        metavar="USD",
+        help=(
+            "Monthly cost review input in USD (default: the retained run's value, "
+            "otherwise 1500); not a billing cap"
+        ),
+    )
+    settings.add_argument(
+        "--work-dir",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Private run directory (default: ~/.local/state/fdai/azure)",
+    )
+    settings.add_argument(
+        "--foundation-workload",
+        default="fdai",
+        metavar="TOKEN",
+        help=(
+            "Foundation naming token for a new source installation "
+            "(default: %(default)s); repeat unchanged on approval resume"
+        ),
+    )
+    settings.add_argument(
+        "--catalog-review-profile",
+        type=Path,
+        metavar="PATH",
+        help=(
+            "Private reviewed GitHub App profile; omit for an explicit skipped "
+            "catalog-review checkpoint"
+        ),
+    )
+    settings.add_argument(
+        "--evidence-verifier-input",
+        type=Path,
+        metavar="PATH",
+        dest="operational_evidence_verifier_input",
+        help=(
+            "Private reviewed verifier deployment input; omit to keep the independent "
+            "operational evidence verifier disabled"
+        ),
+    )
+    settings.add_argument(
+        "--notification-recipients",
+        type=Path,
+        metavar="PATH",
+        dest="notification_recipients",
+        help=(
+            'Private JSON file {"recipients": ["name@domain"]} for the notifications add-on '
+            "on a source AKS installation; required with that add-on, never stored in the profile"
+        ),
+    )
+    settings.add_argument(
+        "--development-authority-profile",
+        type=Path,
+        metavar="PATH",
+        help=("Private reviewed full-authority development profile; source AKS deployment only"),
+    )
+    settings.add_argument(
+        "--clear-development-profile",
+        action="store_true",
+        dest="clear_development_authority_profile",
+        help="Explicitly remove a retained source-AKS development profile through a new plan",
+    )
+    settings.add_argument(
+        "--add-on",
+        action="append",
+        choices=tuple(item.value for item in ProductAddOn),
+        default=[],
+        dest="product_add_ons",
+        metavar="ADD_ON",
+        help=(
+            "Explicit optional product surface; repeat for multiple add-ons. "
+            "The observation-first default selects none"
+        ),
+    )
+    settings.add_argument(
+        "--observation-source",
+        action="append",
+        choices=tuple(item.value for item in ObservationDataSource),
+        default=[],
+        dest="observation_data_sources",
+        metavar="SOURCE",
+        help=("Optional observation source; its minimum read-only role is derived by the profile"),
+    )
+    initial = azure.add_argument_group("Initial source installation scope")
+    initial.add_argument(
+        "--setup-cost-ceiling",
+        type=int,
+        metavar="USD",
+        help="Setup cost estimate ceiling; requested at initial confirmation if omitted",
+    )
+    initial.add_argument(
+        "--console-access",
+        choices=("public-https-entra", "private-https-entra"),
+        default=None,
+        metavar="ACCESS",
+        help=(
+            "Console exposure for an explicitly selected read-only-console add-on; "
+            "the observation-first default is headless"
+        ),
+    )
+    initial.add_argument(
+        "--allow-dedicated-identities",
+        action="store_true",
+        help="Include dedicated identities and minimum role assignments in the initial scope",
+    )
+    initial.add_argument(
+        "--cleanup-temporary-resources",
+        action="store_true",
+        help="Include cleanup of this run's temporary resources; retain services and data",
+    )
+    settings.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=14_400,
+        metavar="SECONDS",
+        help=(
+            "Foundation supervision budget in seconds (default: 14400, 4 hours); "
+            "not a whole-deployment deadline"
+        ),
+    )
+    output = azure.add_argument_group("Output")
+    output.add_argument(
+        "--output",
+        choices=("text", "json"),
+        default="text",
+        help="Final result format (default: text); json disables progress",
+    )
+    output.add_argument(
+        "--progress",
+        choices=("auto", "stream", "plain", "off"),
+        default="auto",
+        help=(
+            "Live view, append-only color stream, plain logs, or off (default: auto); "
+            "source deployment maps auto to the installer stream; json disables it"
+        ),
+    )
+    advanced = azure.add_argument_group("Advanced (optional)")
+    advanced.add_argument(
+        "--control-package",
+        type=Path,
+        metavar="PATH",
+        help="Signed deployment-control wheelhouse for the managed host (--offline-kit only)",
+    )
+    advanced.add_argument(
+        "--trial-token",
+        type=Path,
+        metavar="PATH",
+        help="Private pre-issued capability-token file; never pass the token value",
+    )
+    adoption = azure.add_argument_group("Recovered public deployment (advanced)")
+    adoption.add_argument(
+        "--adopt-runner-image-receipt",
+        type=Path,
+        metavar="PATH",
+        help="Verified runner-image receipt to reuse without another image apply",
+    )
+    adoption.add_argument(
+        "--adopt-application-state",
+        type=Path,
+        metavar="PATH",
+        help="Recovered owner-only public-development Terraform state",
+    )
+    adoption.add_argument(
+        "--adopt-application-recovery",
+        type=Path,
+        metavar="PATH",
+        help="Verified contributor recovery receipt for the state",
+    )
+    adoption.add_argument(
+        "--adopt-resolved-models",
+        type=Path,
+        metavar="PATH",
+        help="Resolved model manifest paired with the recovered state",
+    )
+    foundation_adoption = azure.add_argument_group("Foundation adoption (advanced)")
+    foundation_adoption.add_argument(
+        "--adopt-foundation-directory",
+        type=Path,
+        metavar="PATH",
+        help="Retained source Foundation directory containing its profile and SSH key",
+    )
+    foundation_adoption.add_argument(
+        "--adopt-foundation-recovery",
+        type=Path,
+        metavar="PATH",
+        help="Verified recovery, enrollment, state, authority, and host-key evidence",
+    )
+    azure.set_defaults(handler=handlers["provision_azure"])
+
+    entra = command(
+        provision_commands,
+        "entra",
+        "Observe or apply only the tenant-local FDAI Entra configuration",
+        epilog=(
+            "Without --apply this command is read-only. Apply requires a current interactive "
+            "exact-plan approval and never runs Foundation or application deployment."
+        ),
+    )
+    entra.add_argument(
+        "--source",
+        type=Path,
+        required=True,
+        help="Clean source checkout containing the identity-only coordinator",
+    )
+    entra.add_argument(
+        "--work-dir",
+        type=Path,
+        required=True,
+        help="Absolute private directory for approval, claim, and receipt records",
+    )
+    entra.add_argument(
+        "--target-profile",
+        type=Path,
+        required=True,
+        help="Current-UID mode-0600 target and approved-executor profile",
+    )
+    entra.add_argument(
+        "--control-profile",
+        type=Path,
+        required=True,
+        help="Current-UID mode-0600 reviewed identity-control profile",
+    )
+    entra.add_argument(
+        "--apply",
+        action="store_true",
+        help="Apply the exact Entra app/group plan after current interactive approval",
+    )
+    entra.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=600,
+        help="Total operation deadline from 30 through 1800 seconds (default: %(default)s)",
+    )
+    entra.add_argument("--output", choices=("text", "json"), default="text")
+    entra.set_defaults(handler=handlers["provision_entra"])
+
+    source_change_parser.register(
+        provision_commands,
+        command=command,
+        handlers=handlers,
+    )
+
+    source_update = command(
+        provision_commands,
+        "source-service-update",
+        "Build and deploy one service from a clean source checkout",
+    )
+    source_update.add_argument("--source", type=Path, required=True)
+    source_update.add_argument("--service", choices=sorted(AKS_SERVICES), required=True)
+    source_update.add_argument("--application-work-dir", type=Path, required=True)
+    source_update.add_argument(
+        "--development-authority-profile",
+        type=Path,
+        help="Private reviewed profile for a Core update",
+    )
+    source_update.add_argument(
+        "--clear-development-profile",
+        action="store_true",
+        dest="clear_development_authority_profile",
+        help="Remove the retained profile during a Core update",
+    )
+    source_update.add_argument(
+        "--adopt-historical-binding",
+        type=Path,
+        help="Private execution binding for a retained AKS application baseline",
+    )
+    source_update.add_argument(
+        "--adopt-historical-state",
+        type=Path,
+        help="Retained Terraform state for the AKS application baseline",
+    )
+    source_update.add_argument(
+        "--adopt-historical-variables",
+        type=Path,
+        help="Retained workload variables paired with the Terraform state",
+    )
+    source_update.add_argument(
+        "--adopt-historical-live",
+        type=Path,
+        help="Retained live Deployment snapshot paired with the Terraform state",
+    )
+    source_update.add_argument(
+        "--adopt-historical-plan",
+        type=Path,
+        help="Retained exact Terraform plan for the historical deployment change",
+    )
+    source_update.add_argument("--work-dir", type=Path)
+    source_update.add_argument("--timeout-seconds", type=int, default=14400)
+    source_update.add_argument("--output", choices=("text", "json"), default="text")
+    source_update.set_defaults(handler=handlers["provision_source_service_update"])
+    console_update = command(
+        provision_commands,
+        "console-update",
+        "Plan or apply an exact existing-development Console update",
+        epilog="Create a private plan first. Apply requires its exact digest in a real terminal.",
+    )
+    console_update_commands = command_group(console_update)
+    console_build = command(
+        console_update_commands,
+        "build",
+        "Build a deterministic artifact from protected Git source without Azure access",
+    )
+    console_build.add_argument(
+        "--source", type=Path, required=True, help="Git checkout containing protected origin/main"
+    )
+    console_build.add_argument(
+        "--revision", default="HEAD", help="Protected origin/main revision or ancestor"
+    )
+    console_build.add_argument(
+        "--output-dir", type=Path, required=True, help="New private artifact directory"
+    )
+    console_build.add_argument(
+        "--timeout-seconds", type=int, default=900, help="Bound for the offline Console build"
+    )
+    console_build.add_argument(
+        "--output", choices=("text", "json"), default="text", help="Result format"
+    )
+    console_build.set_defaults(handler=handlers["provision_console_update_build"])
+    console_plan = command(
+        console_update_commands,
+        "plan",
+        "Seal candidate, rollback, source, and Azure target without publishing",
+    )
+    console_plan.add_argument(
+        "--source", type=Path, required=True, help="Clean checkout at protected origin/main"
+    )
+    console_plan.add_argument(
+        "--candidate-archive", type=Path, required=True, help="Candidate Console archive"
+    )
+    console_plan.add_argument(
+        "--candidate-manifest", type=Path, required=True, help="Candidate source manifest"
+    )
+    console_plan.add_argument(
+        "--rollback-archive", type=Path, required=True, help="Known-good rollback archive"
+    )
+    console_plan.add_argument(
+        "--rollback-manifest", type=Path, required=True, help="Rollback source manifest"
+    )
+    console_plan.add_argument(
+        "--target", type=Path, required=True, help="Mode-0600 existing Console target manifest"
+    )
+    console_plan.add_argument(
+        "--work-dir", type=Path, required=True, help="New private plan directory"
+    )
+    console_plan.add_argument(
+        "--ttl-seconds", type=int, default=1200, help="Plan validity in seconds, at most 1200"
+    )
+    console_plan.add_argument(
+        "--output", choices=("text", "json"), default="text", help="Result format"
+    )
+    console_plan.set_defaults(handler=handlers["provision_console_update_plan"])
+    console_apply = command(
+        console_update_commands,
+        "apply",
+        "Publish one explicitly invoked exact dev plan and verify readback",
+        epilog=(
+            "Invocation is explicit coding-session authorization; plan digests remain internally bound."
+        ),
+    )
+    console_apply.add_argument(
+        "--source", type=Path, required=True, help="Clean checkout at the planned source revision"
+    )
+    console_apply.add_argument(
+        "--work-dir", type=Path, required=True, help="Private directory containing the exact plan"
+    )
+    console_apply.add_argument(
+        "--timeout-seconds", type=int, default=900, help="Bound for publication and readback"
+    )
+    console_apply.add_argument(
+        "--output", choices=("text", "json"), default="text", help="Result format"
+    )
+    console_apply.set_defaults(handler=handlers["provision_console_update_apply"])
+    register_state_handoff_command(provision_commands)
+    register_foundation_plan_command(provision_commands)
+    initialize = command(provision_commands, "init", "Create a private manual deployment profile")
+    initialize.add_argument(
+        "--profile",
+        type=Path,
+        required=True,
+        help="Private profile file to create; replacement requires --force",
+    )
+    initialize.add_argument("--environment", choices=("dev", "staging", "prod"), required=True)
+    initialize.add_argument("--region", required=True)
+    initialize.add_argument("--target-binding", required=True)
+    initialize.add_argument("--connectivity", choices=("online", "offline"), required=True)
+    initialize.add_argument("--host", choices=("existing-host", "managed-vm"), required=True)
+    initialize.add_argument("--transport", choices=("manual",), required=True)
+    initialize.add_argument(
+        "--access-method",
+        choices=(
+            "internal_ssh",
+            "temporary_public_ssh",
+            "bastion",
+            "run_command",
+        ),
+        required=True,
+    )
+    initialize.add_argument("--approval-quorum", type=int, default=1)
+    initialize.add_argument("--monthly-cost-ceiling", type=int, default=0)
+    initialize.add_argument("--force", action="store_true")
+    initialize.add_argument("--output", choices=("text", "json"), default="text")
+    initialize.set_defaults(handler=handlers["provision_init"])
+
+    inspect = command(
+        provision_commands, "inspect", "Inspect a profile and local deployment prerequisites"
+    )
+    inspect.add_argument("--profile", type=Path, required=True)
+    inspect.add_argument("--output", choices=("text", "json"), default="text")
+    inspect.set_defaults(handler=handlers["provision_inspect"])
+
+    plan = command(
+        provision_commands, "plan", "Plan a verified Terraform root without applying changes"
+    )
+    plan_source = plan.add_mutually_exclusive_group(required=True)
+    plan_source.add_argument(
+        "--offline-kit",
+        type=Path,
+        help="Complete signed deployment kit; release and bundle keys required",
+    )
+    plan_source.add_argument(
+        "--source-snapshot", type=Path, help="Private prepared source snapshot (Foundation only)"
+    )
+    plan.add_argument(
+        "--source-snapshot-digest",
+        metavar="SHA256",
+        help="Independently retained source snapshot SHA-256",
+    )
+    plan.add_argument(
+        "--terraform",
+        type=Path,
+        help="Terraform executable matching the committed source toolchain",
+    )
+    plan.add_argument("--release-root", type=Path)
+    plan.add_argument("--bundle-public-key", type=Path)
+    plan.add_argument("--work-dir", type=Path, required=True)
+    plan.add_argument("--variables-file", type=Path, required=True)
+    plan.add_argument("--profile", type=Path, required=True)
+    plan.add_argument("--stage", choices=("platform", "foundation"), default="platform")
+    plan.add_argument(
+        "--save-plan",
+        action="store_true",
+        help="retain a private foundation plan and review digest; does not authorize apply",
+    )
+    plan.add_argument("--output", choices=("text", "json"), default="text")
+    plan.set_defaults(handler=handlers["provision_plan"])
+
+    bootstrap_reconcile = command(
+        provision_commands,
+        "bootstrap-reconcile",
+        "Read Azure Foundation state into an expiring plan",
+    )
+    bootstrap_reconcile.add_argument("--profile", type=Path, required=True)
+    bootstrap_reconcile.add_argument("--source-commit", required=True)
+    bootstrap_reconcile.add_argument("--ops-resource-group", required=True)
+    bootstrap_reconcile.add_argument("--app-resource-group", required=True)
+    bootstrap_reconcile.add_argument("--state-storage-account", required=True)
+    bootstrap_reconcile.add_argument("--output-plan", type=Path, required=True)
+    bootstrap_reconcile.add_argument("--ttl-seconds", type=int, default=3600)
+    bootstrap_reconcile.add_argument("--output", choices=("text", "json"), default="text")
+    bootstrap_reconcile.set_defaults(handler=handlers["provision_bootstrap_reconcile"])
+
+    bundle = command(
+        subcommands,
+        "bundle",
+        "Verify deployment-bundle signatures and integrity",
+        epilog="Next: fdaictl bundle verify --help",
+    )
+    bundle_commands = command_group(bundle)
+    bundle_verify = command(
+        bundle_commands, "verify", "Verify signature, compatibility, files, and digests"
+    )
+    bundle_verify.add_argument("--bundle", type=Path, required=True)
+    bundle_verify.add_argument("--public-key", type=Path, required=True)
+    bundle_verify.add_argument("--output", choices=("text", "json"), default="text")
+    bundle_verify.set_defaults(handler=handlers["bundle_verify"])
+
+    license_command = command(
+        subcommands,
+        "license",
+        "Inspect or seal existing licensing bytes without granting authority",
+        epilog="Next: fdaictl license inspect --help",
+    )
+    license_commands = command_group(license_command)
+    license_inspect = command(
+        license_commands, "inspect", "Verify a local token and report its declared capabilities"
+    )
+    license_inspect.add_argument("--token", type=Path, required=True)
+    license_inspect.add_argument("--public-key", type=Path, required=True)
+    license_inspect.add_argument("--image-digest", default=None)
+    license_inspect.add_argument("--tenant-binding", default=None)
+    license_inspect.add_argument("--installation-binding", default=None, metavar="DIGEST")
+    license_inspect.add_argument("--output", choices=("text", "json"), default="text")
+    license_inspect.set_defaults(handler=handlers["license_inspect"])
+    license_seal = command(
+        license_commands,
+        "seal-entitlement",
+        "Seal an existing token to an independently supplied installation recipient",
+    )
+    license_seal.add_argument(
+        "--token",
+        type=Path,
+        required=True,
+        help="Private file containing existing original token bytes",
+    )
+    license_seal.add_argument(
+        "--recipient-public-key",
+        type=Path,
+        required=True,
+        help="Private file containing the independently provisioned X25519 recipient public key",
+    )
+    license_seal.add_argument(
+        "--installation-binding",
+        required=True,
+        metavar="DIGEST",
+        help="Exact installation SHA-256 binding",
+    )
+    license_seal.add_argument(
+        "--deployment-binding",
+        required=True,
+        metavar="DIGEST",
+        help="Exact deployment SHA-256 binding",
+    )
+    license_seal.add_argument(
+        "--destination",
+        type=Path,
+        required=True,
+        help="New owner-only encrypted carrier output file",
+    )
+    license_seal.set_defaults(handler=handlers["license_seal_entitlement"])
+
+    onboard = command(
+        subcommands,
+        "onboard",
+        "Run a local simulation or read its journal",
+        epilog=(
+            "Simulation only: fdaictl onboard guided --help\n"
+            "For live deployment use fdaictl provision azure --help."
+        ),
+    )
+    onboard_commands = command_group(onboard)
+    guided = command(
+        onboard_commands,
+        "guided",
+        "Rehearse the stage graph; requires --simulate and never deploys",
+    )
+    guided.add_argument("--profile", type=Path, required=True)
+    guided.add_argument("--source-commit", required=True)
+    guided.add_argument("--run-id", required=True)
+    guided.add_argument("--journal", type=Path, required=True)
+    guided.add_argument("--simulate", action="store_true")
+    guided.add_argument("--interrupt-after", default=None)
+    guided.add_argument("--output", choices=("text", "json"), default="text")
+    guided.set_defaults(handler=handlers["onboard_guided"])
+    status = command(onboard_commands, "status", "Read progress from a local simulation journal")
+    status.add_argument("--journal", type=Path, required=True)
+    status.add_argument("--output", choices=("text", "json"), default="text")
+    status.set_defaults(handler=handlers["onboard_status"])
+    return parser