acumatica-cli 0.2.2__py3-none-any.whl

acumatica_cli/bootstrap.py

@@ -0,0 +1,105 @@
+"""Bootstrap customization package: build the zip, publish via /CustomizationApi.
+
+An unconfigured tenant cannot be configured through the Default endpoint
+(features are off, no company/branch exists, credit terms have no entity —
+docs/rest-api.md). The CustomizationApi is the one door that works on a
+virgin tenant, so bootstrap = publish a package whose CustomizationPlugin
+(`bootstrap_plugin.cs`) enables features on publish — the contract API
+cannot write CS100000 at all (T3 verdict) — and whose Bootstrap contract
+endpoint exposes CS101500 company + CS206500 credit terms for seeding
+(`bootstrap_project.xml`, serialization verified T12).
+
+Customization publishes are tenant-scoped, so the package must be published
+per tenant; publish() is idempotent — an already-published package is a
+no-op skip, and the plugin's UpdateDatabase is a keyed update on re-run.
+"""
+
+import io
+import time
+import xml.etree.ElementTree as ET
+import zipfile
+from importlib import resources
+
+import httpx
+
+from .client import AcumaticaClient
+
+# Alphanumeric only: CstDbStorage.ValidatePackageName rejects '-' and '_'
+# (verified vs 26.101.0225 — "Invalid project name")
+PACKAGE_NAME = "AcuBootstrap"
+PACKAGE_DESCRIPTION = (
+    "acu bootstrap: CustomizationPlugin enables features on publish; "
+    "Bootstrap endpoint exposes company + credit terms"
+)
+PLUGIN_CLASS = "AcuBootstrapPlugin"
+
+
+def package_zip() -> bytes:
+    """Build the customization package: a zip holding project.xml.
+
+    The C# plugin travels as a <Graph> item whose Source ATTRIBUTE holds the
+    file content (Customization.CstCodeFile shape, verified vs 26.101.0225:
+    inline CDATA and zip-file variants are silently dropped on import).
+    ElementTree escapes the newlines as &#10; on serialization.
+    """
+    pkg = resources.files("acumatica_cli")
+    root = ET.fromstring((pkg / "bootstrap_project.xml").read_bytes())
+    graph = ET.SubElement(root, "Graph")
+    graph.set("ClassName", PLUGIN_CLASS)
+    graph.set("FileType", "NewFile")
+    graph.set("Source", (pkg / "bootstrap_plugin.cs").read_text(encoding="utf-8"))
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("project.xml", ET.tostring(root, encoding="utf-8"))
+    return buf.getvalue()
+
+
+def _log_tail(status: dict[str, object], limit: int = 5) -> str:
+    """Last few publish-log messages, for a one-line error (SPEC V9)."""
+    log = status.get("log")
+    if not isinstance(log, list):
+        return ""
+    messages = [
+        str(entry.get("message", "")) for entry in log if isinstance(entry, dict)
+    ]
+    return "; ".join(m for m in messages[-limit:] if m)
+
+
+def publish(client: AcumaticaClient, timeout: float = 600.0, poll: float = 5.0) -> str:
+    """Publish the bootstrap package into the client's session tenant.
+
+    Idempotent: returns ``"already published"`` when getPublished lists the
+    package AND its content still exists (a recreated tenant with the same
+    CompanyID keeps the stale publication row while the content and the
+    plugin's writes are gone), else import -> publishBegin -> poll publishEnd
+    until the server reports completion. Transport errors while polling are
+    tolerated — publishing restarts the app domain, so the site may briefly
+    drop connections mid-publish. Raises RuntimeError on a failed publish or
+    on timeout.
+    """
+    if PACKAGE_NAME in client.customization_published() and (
+        client.customization_project_exists(PACKAGE_NAME)
+    ):
+        return "already published"
+    client.customization_import(
+        PACKAGE_NAME, package_zip(), description=PACKAGE_DESCRIPTION
+    )
+    client.customization_publish_begin([PACKAGE_NAME])
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            status = client.customization_publish_end()
+        except httpx.TransportError:
+            status = {}  # site restarting mid-publish; keep polling
+        if status.get("isFailed"):
+            detail = _log_tail(status)
+            raise RuntimeError(
+                f"publishing {PACKAGE_NAME} failed" + (f": {detail}" if detail else "")
+            )
+        if status.get("isCompleted"):
+            return "published"
+        if time.monotonic() >= deadline:
+            raise RuntimeError(
+                f"publishing {PACKAGE_NAME} did not complete within {timeout:.0f}s"
+            )
+        time.sleep(poll)

acumatica_cli/bootstrap_plugin.cs

@@ -0,0 +1,62 @@
+// acu bootstrap CustomizationPlugin (SPEC T11).
+//
+// Runs in-process on customization publish - the one write path to
+// FeaturesSet that works: the contract API cannot persist features no
+// matter what endpoint fronts CS100000 (T3 verdict, docs/rest-api.md).
+//
+// Deliberately writes through PXDatabase, not FeaturesMaint: the graph
+// save collides with the publish pipeline's concurrent plugin invocations
+// ("Another process has added the 'FeaturesSet' record" - observed live,
+// 26.101.0225) and nothing persists. A keyed row write is deterministic
+// and idempotent: update the existing row, insert when absent. All 205
+// NOT NULL bit columns are filled reflectively (only ~136 carry DB
+// defaults); Status = 0 means Validated (PXIntList, verified vs live).
+using System.Collections.Generic;
+using System.Reflection;
+using PX.Data;
+using PX.Objects.CS;
+
+namespace AcuBootstrap
+{
+    public class AcuBootstrapPlugin : Customization.CustomizationPlugin
+    {
+        private static readonly HashSet<string> Enabled = new HashSet<string>
+        {
+            "FinancialModule",
+            "FinancialStandard",
+            "DistributionModule",
+            "Inventory",
+            "Branch",
+            "MultiCompany",
+        };
+
+        public override void UpdateDatabase()
+        {
+            var flags = new List<PXDataFieldAssign>();
+            foreach (PropertyInfo prop in typeof(FeaturesSet).GetProperties())
+            {
+                if (prop.PropertyType == typeof(bool?))
+                {
+                    flags.Add(new PXDataFieldAssign(
+                        prop.Name, PXDbType.Bit, Enabled.Contains(prop.Name)));
+                }
+            }
+            flags.Add(new PXDataFieldAssign("Status", PXDbType.Int, 0)); // Validated
+
+            using (var tx = new PXTransactionScope())
+            {
+                bool updated = PXDatabase.Update<FeaturesSet>(flags.ToArray());
+                if (!updated)
+                {
+                    PXDatabase.Insert<FeaturesSet>(flags.ToArray());
+                    WriteLog("AcuBootstrap: FeaturesSet row inserted (features enabled)");
+                }
+                else
+                {
+                    WriteLog("AcuBootstrap: FeaturesSet row updated (features enabled)");
+                }
+                tx.Complete();
+            }
+        }
+    }
+}

acumatica_cli/bootstrap_project.xml

@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  acu bootstrap customization package template (SPEC T2 + T11 + T12).
+
+  package_zip() (bootstrap.py) parses this template and injects a
+  <Graph ClassName="AcuBootstrapPlugin" FileType="NewFile" Source="..."/>
+  item carrying bootstrap_plugin.cs - the CustomizationPlugin that enables
+  features on publish (CS100000 is un-writable through the contract API;
+  T3 verdict). Item shape verified vs 26.101.0225: Customization.CstCodeFile
+  Tag=Graph, source rides in the Source ATTRIBUTE (XML-escaped), not CDATA.
+
+  Root element shape verified vs the training packages shipped on the live
+  box (HelpAndTraining/T*/PhoneRepairShop.zip, same 26.101.0225 build):
+  project.xml's root is <Customization level description product-version>;
+  the project NAME comes from the import call, not the XML.
+
+  The <EntityEndpoint> item (T12, verified vs 26.101.0225 by import
+  round-trip 2026-07-08): the <Endpoint> child is the XmlSerializer form of
+  PX.Api.ContractBased.Common.Model.Endpoint - namespace
+  http://www.acumatica.com/entity/maintenance/5.31 (the earlier
+  entity/data-model guess is what the importer rejected as "Unknown root
+  node"), systemContractVersion 4 (SystemContracts.V4, the build's only
+  IsCurrent implementation). No .endpoint file is involved - the
+  PX.Api.ContractBased.Common.dll "*.endpoint" globs belong to the
+  source-control folder layout, not the package zip. The server's own
+  getProject re-serialization carries no attributes on <EntityEndpoint>;
+  identity comes from the child's name/version.
+
+  Entity payload (screen->graph->view->DAC chain read off the live box):
+  - Company    CS101500 -> OrganizationMaint, PrimaryView BAccount
+                (DAC PX.Objects.CS.DAC.OrganizationBAccount); the old
+                draft's Organization view / OrganizationCD do not exist on
+                this build. Mappings follow the screen's OWN bindings
+                (CS101500.aspx read off the live box, T13) - a DAC prop
+                existing on the primary view is not enough, writes only
+                land through the view the screen edits:
+                - AcctCD/AcctName -> BAccount (primary view);
+                - OrganizationType/BaseCuryID -> OrganizationView
+                  (PX.Objects.GL.DAC.Organization; the BAccount projections
+                  of these echo the PUT but insert an empty GL row - 422
+                  "BaseCuryID cannot be empty");
+                - CountryID -> AddressDummy (PX.Objects.CR.Address, the
+                  Main Address binding; the graph inserts the Address row
+                  on first save and its CountryID is required - 422).
+  - CreditTerms CS206500 -> TermsMaint, PrimaryView TermsDef
+                (DAC PX.Objects.CS.Terms); DayDue00 is Nullable<Int16>
+                -> ShortValue, DiscPercent Nullable<Decimal> -> DecimalValue.
+  Contract field names = DAC property names verbatim (no rename layer).
+  Features (CS100000) stays OUT of the endpoint - writes through any
+  contract endpoint do not persist (T3 verdict); the plugin owns features.
+-->
+<Customization level="" description="acu bootstrap: CustomizationPlugin enables features on publish; Bootstrap endpoint exposes company + credit terms" product-version="26.101">
+  <EntityEndpoint>
+    <Endpoint xmlns="http://www.acumatica.com/entity/maintenance/5.31" name="Bootstrap" version="1.0.0" systemContractVersion="4">
+      <TopLevelEntity name="Company" screen="CS101500">
+        <Fields>
+          <Field name="AcctCD" type="StringValue" />
+          <Field name="AcctName" type="StringValue" />
+          <Field name="OrganizationType" type="StringValue" />
+          <Field name="BaseCuryID" type="StringValue" />
+          <Field name="CountryID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="AcctCD">
+            <To object="BAccount" field="AcctCD" />
+          </Mapping>
+          <Mapping field="AcctName">
+            <To object="BAccount" field="AcctName" />
+          </Mapping>
+          <Mapping field="OrganizationType">
+            <To object="OrganizationView" field="OrganizationType" />
+          </Mapping>
+          <Mapping field="BaseCuryID">
+            <To object="OrganizationView" field="BaseCuryID" />
+          </Mapping>
+          <Mapping field="CountryID">
+            <To object="AddressDummy" field="CountryID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="CreditTerms" screen="CS206500">
+        <Fields>
+          <Field name="TermsID" type="StringValue" />
+          <Field name="Descr" type="StringValue" />
+          <Field name="VisibleTo" type="StringValue" />
+          <Field name="DueType" type="StringValue" />
+          <Field name="DayDue00" type="ShortValue" />
+          <Field name="DiscType" type="StringValue" />
+          <Field name="DiscPercent" type="DecimalValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="TermsID">
+            <To object="TermsDef" field="TermsID" />
+          </Mapping>
+          <Mapping field="Descr">
+            <To object="TermsDef" field="Descr" />
+          </Mapping>
+          <Mapping field="VisibleTo">
+            <To object="TermsDef" field="VisibleTo" />
+          </Mapping>
+          <Mapping field="DueType">
+            <To object="TermsDef" field="DueType" />
+          </Mapping>
+          <Mapping field="DayDue00">
+            <To object="TermsDef" field="DayDue00" />
+          </Mapping>
+          <Mapping field="DiscType">
+            <To object="TermsDef" field="DiscType" />
+          </Mapping>
+          <Mapping field="DiscPercent">
+            <To object="TermsDef" field="DiscPercent" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+    </Endpoint>
+  </EntityEndpoint>
+</Customization>

acumatica_cli/cli.py

@@ -0,0 +1,351 @@
+"""acu - Acumatica configuration as code.
+
+acu provision --id N --login T   one command: create -> bootstrap -> apply -> diff
+acu tenant list|create|delete    tenant CRUD (ac.exe over SSH)
+acu apply [--dry-run] FILES...   seed baseline YAML via the REST API
+acu diff FILES...                drift check: baseline vs live tenant
+acu schema [--out DIR]           dump the endpoint's OpenAPI schema
+acu config show                  print the resolved target instance
+"""
+
+import os
+from pathlib import Path
+
+import click
+import httpx
+import yaml
+
+from . import bootstrap, firstlogin, output, seed
+from .client import AcumaticaClient
+from .config import Instance, data_root, load_instance
+from .tenant import TenantManager
+
+
+@click.group(help=__doc__)
+@click.version_option(package_name="acumatica-cli")
+@click.option(
+    "-t", "--tenant", default=None, help="Override the tenant API sessions sign in to"
+)
+@click.option(
+    "--host",
+    default=None,
+    help="Override the acu.yaml host (base_url/ssh re-derive from it)",
+)
+@click.pass_context
+def cli(ctx: click.Context, tenant: str | None, host: str | None) -> None:
+    """Resolve the target instance and stash it in the Click context."""
+    inst = load_instance(host=host)
+    if tenant is not None:
+        inst = inst.model_copy(update={"tenant": tenant})
+    ctx.obj = inst
+
+
+def main() -> None:
+    """Entry point: run the CLI, mapping expected failures to one-line errors.
+
+    RuntimeError (SSH/ac.exe, REST, first-login) and httpx transport errors
+    print `x message` and exit 1; ACU_DEBUG=1 re-raises for the traceback.
+    """
+    try:
+        cli()
+    except (RuntimeError, httpx.HTTPError) as exc:
+        if os.environ.get("ACU_DEBUG"):
+            raise
+        output.error(str(exc))
+        raise SystemExit(1) from exc
+
+
+@cli.group("tenant")
+def tenant_group() -> None:
+    """Tenant CRUD on the instance (ac.exe CompanyConfig over SSH)."""
+
+
+@tenant_group.command("list")
+@click.pass_obj
+def tenant_list(inst: Instance) -> None:
+    """List tenants: CompanyID, sign-in name, internal CD, type."""
+    tenants = TenantManager(inst).list()
+    output.table(
+        f"Tenants on {inst.host}",
+        ("ID", "Login", "CD", "Type"),
+        (
+            (str(t.company_id), t.login_name, t.company_cd, t.company_type)
+            for t in tenants
+        ),
+    )
+
+
+@tenant_group.command("create")
+@click.option(
+    "--id",
+    "company_id",
+    type=int,
+    required=True,
+    help="CompanyID (first free is usually 3)",
+)
+@click.option(
+    "--login",
+    "login_name",
+    required=True,
+    help="Acumatica tenant name as shown on the sign-in page",
+)
+@click.option(
+    "--type",
+    "company_type",
+    default="",
+    help="Inserted data set: '' = clean, SalesDemo = demo",
+)
+@click.option("--parent", "parent_id", type=int, default=1, show_default=True)
+@click.option("--hidden", is_flag=True, help="Do not show on the sign-in page")
+@click.option(
+    "--no-init",
+    is_flag=True,
+    help="Skip app-pool recycle + first-login password change",
+)
+@click.pass_obj
+def tenant_create(
+    inst: Instance,
+    company_id: int,
+    login_name: str,
+    company_type: str,
+    parent_id: int,
+    hidden: bool,
+    no_init: bool,
+) -> None:
+    """Create a tenant and make it automation-ready.
+
+    Chains the verified steps (docs/ac-exe.md, docs/rest-api.md): ac.exe
+    CompanyConfig with the admin password preset, an app-pool recycle so the
+    running app sees the tenant, then a REST login check (with the sign-in
+    screen's first-login password-change flow as fallback).
+    """
+    mgr = TenantManager(inst)
+    with output.step(f"creating tenant {company_id} ({login_name}) on {inst.host}"):
+        raw = mgr.create(company_id, login_name, parent_id, not hidden, company_type)
+    output.data(raw.splitlines()[-1] if raw.strip() else "created")
+    if no_init:
+        output.warn("skipping init: tenant is invisible until an app-pool recycle")
+        return
+    _init_tenant(inst, mgr, login_name)
+
+
+def _init_tenant(inst: Instance, mgr: TenantManager, login_name: str) -> None:
+    """Make a freshly created tenant automation-ready (V5 recycle + login check)."""
+    with output.step("recycling app pool (tenant map loads at app start)"):
+        mgr.recycle_app_pool()
+    with output.step("verifying REST login (screen-flow password change as fallback)"):
+        result = firstlogin.initialize_admin_password(inst, tenant=login_name)
+    output.success(f"admin {result}; tenant {login_name} is ready")
+
+
+@tenant_group.command("delete")
+@click.option("--id", "company_id", type=int, required=True)
+@click.confirmation_option(prompt="Delete this tenant and all its data?")
+@click.pass_obj
+def tenant_delete(inst: Instance, company_id: int) -> None:
+    """Delete the tenant and all its data, then recycle the app pool."""
+    mgr = TenantManager(inst)
+    raw = mgr.delete(company_id)
+    output.data(raw.splitlines()[-1] if raw.strip() else "done")
+    with output.step("recycling app pool (drops the tenant from the running app)"):
+        mgr.recycle_app_pool()
+
+
+@cli.group("config")
+def config_group() -> None:
+    """Local read-only config inspection (never talks to a live instance)."""
+
+
+@config_group.command("show")
+@click.pass_obj
+def config_show(inst: Instance) -> None:
+    """Print the fully resolved instance as a complete acu.yaml document.
+
+    Resolves through the same load_instance path every live command uses,
+    so the printed values are exactly what a live command would trust.
+    Credentials never appear - redirect to a file and edit: the output
+    loads back through load_instance unchanged.
+    """
+    doc = inst.model_dump(exclude={"username", "password"})
+    output.data("# resolved by `acu config show` - a complete acu.yaml")
+    output.data(
+        "# credentials come from .env (ACU_USER / ACU_PASSWORD), never from here"
+    )
+    for line in yaml.safe_dump(doc, sort_keys=False).splitlines():
+        output.data(line)
+
+
+def expand_files(files: tuple[Path, ...]) -> list[Path]:
+    """Expand directory arguments into their *.yaml files, sorted."""
+    paths: list[Path] = []
+    for path in files:
+        if path.is_dir():
+            found = sorted(path.glob("*.yaml"))
+            if not found:
+                raise SystemExit(f"{path}: no *.yaml files in directory")
+            paths += found
+        else:
+            paths.append(path)
+    return paths
+
+
+@cli.command("provision")
+@click.option(
+    "--id",
+    "company_id",
+    type=int,
+    required=True,
+    help="CompanyID (first free is usually 3)",
+)
+@click.option(
+    "--login",
+    "login_name",
+    required=True,
+    help="Acumatica tenant name as shown on the sign-in page",
+)
+@click.option(
+    "--type",
+    "company_type",
+    default="",
+    help="Inserted data set: '' = clean, SalesDemo = demo",
+)
+@click.option("--parent", "parent_id", type=int, default=1, show_default=True)
+@click.pass_obj
+def provision_cmd(
+    inst: Instance,
+    company_id: int,
+    login_name: str,
+    company_type: str,
+    parent_id: int,
+) -> None:
+    """One command to a configured tenant: create -> bootstrap -> apply -> diff.
+
+    Chains the verified pipeline (docs/rest-api.md) idempotently: tenant
+    create over SSH (skipped when the login name already exists), bootstrap
+    package publish (skipped when already published), bootstrap/ YAML through
+    the custom endpoint, baseline/ through the Default endpoint, then a drift
+    check over everything applied - exit 2 on drift.
+    """
+    root = data_root()
+    baseline_dir = root / "baseline"
+    if not baseline_dir.is_dir():
+        raise SystemExit(f"{baseline_dir}: not a directory - nothing to provision")
+    seed_dirs = [d for d in (root / "bootstrap", baseline_dir) if d.is_dir()]
+    # every session below signs in to the provisioned tenant, never a default
+    inst = inst.model_copy(update={"tenant": login_name})
+
+    mgr = TenantManager(inst)
+    if any(t.login_name == login_name for t in mgr.list()):
+        output.info(f"tenant {login_name} exists on {inst.host} - skipping create")
+    else:
+        with output.step(f"creating tenant {company_id} ({login_name}) on {inst.host}"):
+            raw = mgr.create(company_id, login_name, parent_id, True, company_type)
+        output.data(raw.splitlines()[-1] if raw.strip() else "created")
+        _init_tenant(inst, mgr, login_name)
+
+    with (
+        output.step(f"publishing {bootstrap.PACKAGE_NAME} to {inst.tenant}"),
+        AcumaticaClient(inst) as client,
+    ):
+        result = bootstrap.publish(client)
+    output.success(f"{bootstrap.PACKAGE_NAME} {result}")
+    # unconditional: the publish restarts the site BEFORE its DB transaction
+    # commits, so the restarted domain caches the feature slot pre-plugin
+    # (verified live: gated screens stay 403 until one more recycle); on the
+    # skip path a recycle is the cheap way to make a resumed run sound too
+    with output.step("recycling app pool (feature set loads at app start)"):
+        mgr.recycle_app_pool()
+    with output.step("waiting for the site to come back"):
+        firstlogin.initialize_admin_password(inst, tenant=login_name)
+
+    # fresh session: publishing restarts the app domain, so don't trust the
+    # cookie that watched it happen
+    drifts: list[str] = []
+    seed_paths = expand_files(tuple(seed_dirs))
+    with AcumaticaClient(inst) as client:
+        for path in seed_paths:
+            baseline = seed.load_baseline(path)
+            output.data(f"{path} -> {inst.host}/{inst.tenant} ({baseline.entity})")
+            n = seed.apply(client, baseline)
+            output.data(f"  {n} record(s)")
+        # diff everything applied, bootstrap YAML included - a PUT that
+        # answers 200 can persist nothing (T3), the drift check is the proof
+        for path in seed_paths:
+            drifts += seed.diff(client, seed.load_baseline(path))
+    _exit_on_drift(inst, drifts, len(seed_paths))
+
+
+@cli.command("apply")
+@click.argument(
+    "files", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be PUT without writing")
+@click.pass_obj
+def apply_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
+    """Seed baseline YAML into the tenant (idempotent PUT upserts).
+
+    FILES are baseline YAML files or directories containing them.
+    """
+    with AcumaticaClient(inst) as client:
+        for path in expand_files(files):
+            baseline = seed.load_baseline(path)
+            output.data(f"{path} -> {inst.host}/{inst.tenant} ({baseline.entity})")
+            n = seed.apply(client, baseline, dry_run=dry_run)
+            output.data(f"  {n} record(s){' (dry run)' if dry_run else ''}")
+
+
+@cli.command("schema")
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Output directory (default: <data repo>/schemas)",
+)
+@click.pass_obj
+def schema_cmd(inst: Instance, out_dir: Path | None) -> None:
+    """Dump the endpoint's OpenAPI schema (swagger.json) into schemas/.
+
+    The schema is the authoritative field-level reference for the exact
+    build - regenerate rather than version (the file is ~3 MB).
+    """
+    if out_dir is None:
+        out_dir = data_root() / "schemas"
+    out_file = out_dir / f"swagger-{inst.endpoint.replace('/', '-')}.json"
+    with (
+        output.step(f"dumping OpenAPI schema from {inst.host} ({inst.endpoint})"),
+        AcumaticaClient(inst) as client,
+    ):
+        raw = client.swagger()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_file.write_bytes(raw)
+    output.data(f"{out_file} ({len(raw)} bytes)")
+
+
+@cli.command("diff")
+@click.argument(
+    "files", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path)
+)
+@click.pass_obj
+def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
+    """Compare baseline YAML against the live tenant; exit 2 on drift.
+
+    FILES are baseline YAML files or directories containing them.
+    """
+    paths = expand_files(files)
+    drifts: list[str] = []
+    with AcumaticaClient(inst) as client:
+        for path in paths:
+            baseline = seed.load_baseline(path)
+            drifts += seed.diff(client, baseline)
+    _exit_on_drift(inst, drifts, len(paths))
+
+
+def _exit_on_drift(inst: Instance, drifts: list[str], files: int) -> None:
+    """Report drift lines and exit 2 (the load-bearing diff contract, V9)."""
+    if drifts:
+        output.error(f"DRIFT on {inst.host}/{inst.tenant}:")
+        for line in drifts:
+            output.data(f"  {line}")
+        raise SystemExit(2)
+    output.success(f"no drift on {inst.host}/{inst.tenant} ({files} file(s))")