acumatica-cli 0.7.0__tar.gz → 0.8.1__tar.gz

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.7.0
+Version: 0.8.1
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -10,7 +10,7 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: pydantic-settings>=2.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13
-Requires-Python: >=3.12
+Requires-Python: >=3.14
 Project-URL: Homepage, https://lab5.ca
 Project-URL: Repository, https://github.com/kborovik/acumatica-cli
 Description-Content-Type: text/markdown
@@ -21,22 +21,6 @@ Description-Content-Type: text/markdown
 
 **No UI clicks, no Configuration Wizard.**
 
-## How it works
-
-1. **Extract** the target Acumatica deployment with `acu extract` — its configuration becomes YAML, config as code.
-2. **Develop** changes in the YAML, in git: edit, review, version.
-3. **Re-deploy** with `acu apply`, then prove the live tenant matches the code with `acu diff`.
-
-Four commands do the work, and every one is safe to re-run:
-
-- **`acu tenant create`** — creates a tenant and bootstraps it in one step, ready for `apply`.
-  Re-running it against an existing tenant republishes the bootstrap package instead of failing.
-- **`acu apply`** — pushes your YAML into the tenant as keyed upserts.
-  Running it twice changes nothing.
-- **`acu diff`** — compares your YAML against the live tenant and exits with code 2 on drift.
-- **`acu extract`** — reads a configured tenant and writes the YAML file set back out, the inverse of `apply`.
-  Existing files are skipped unless `--force`.
-
 > **Tested against** Acumatica ERP **26.101.0225** on Windows Server 2025,
 > contract REST endpoint **25.200.001**. Other versions will likely work,
 > but only this combination is verified.
@@ -75,6 +59,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
@@ -86,25 +71,31 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
+`run` called without FILES defaults to `scenario/`.
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
-Your configuration lives in its own git repo, which `acu config init` scaffolds:
+Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
 | Path         | What it holds                                                              |
 | ------------ | -------------------------------------------------------------------------- |
 | `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
 | `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
 | `setup/`     | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
 | `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
 
 Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order. The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
 
+Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+Scenario YAML is different — it describes transactions that flow forward.
+`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so a scenario re-runs safely on a warm tenant.
+
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.14 or newer.
 
 ```sh
 uv tool install acumatica-cli
@@ -148,9 +139,9 @@ acu apply --dry-run    # show what would be written, write nothing
 `acu` talks to an instance over two independent channels:
 
 - **Control plane (SSH):** `acu tenant` runs `ac.exe -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see [`docs/ac-exe.md`](docs/ac-exe.md).
-- **Data plane (REST):** `acu apply`, `diff`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
+- **Data plane (REST):** `acu apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
 
 ## SSH setup (control plane)
 

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/README.md

@@ -4,22 +4,6 @@
 
 **No UI clicks, no Configuration Wizard.**
 
-## How it works
-
-1. **Extract** the target Acumatica deployment with `acu extract` — its configuration becomes YAML, config as code.
-2. **Develop** changes in the YAML, in git: edit, review, version.
-3. **Re-deploy** with `acu apply`, then prove the live tenant matches the code with `acu diff`.
-
-Four commands do the work, and every one is safe to re-run:
-
-- **`acu tenant create`** — creates a tenant and bootstraps it in one step, ready for `apply`.
-  Re-running it against an existing tenant republishes the bootstrap package instead of failing.
-- **`acu apply`** — pushes your YAML into the tenant as keyed upserts.
-  Running it twice changes nothing.
-- **`acu diff`** — compares your YAML against the live tenant and exits with code 2 on drift.
-- **`acu extract`** — reads a configured tenant and writes the YAML file set back out, the inverse of `apply`.
-  Existing files are skipped unless `--force`.
-
 > **Tested against** Acumatica ERP **26.101.0225** on Windows Server 2025,
 > contract REST endpoint **25.200.001**. Other versions will likely work,
 > but only this combination is verified.
@@ -58,6 +42,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │
 ├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
 ├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── run   [--dry-run] [FILES...]      execute transaction scenario YAML (exit 1 on any miss)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     dump live tenant state as seed YAML (inverse of apply)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
@@ -69,25 +54,31 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ```
 
 `apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`.
+`run` called without FILES defaults to `scenario/`.
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
 ## The data repo
 
-Your configuration lives in its own git repo, which `acu config init` scaffolds:
+Your configuration lives in its own git repo. `acu config init` scaffolds everything except `scenario/`, which you author by hand:
 
 | Path         | What it holds                                                              |
 | ------------ | -------------------------------------------------------------------------- |
 | `bootstrap/` | what makes a virgin tenant configurable: features, company, credit terms   |
 | `baseline/`  | reference data: subaccounts, chart of accounts, ledger, units of measure   |
 | `setup/`     | one-time actions: financial year, master calendar, open periods            |
+| `scenario/`  | transaction scenarios for `acu run`: purchase, build, sell flows            |
 | `.env`       | where to apply and who signs in, every key an `ACU_*` variable             |
 
 Files in each directory apply alphabetically; the numbered prefixes (`10-`, `20-`, and so on) encode dependency order. The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for example as `.env.gpg`) and decrypt once per clone.
 
+Seed YAML in `bootstrap/`, `baseline/`, and `setup/` is state: `apply` upserts it, `diff` proves it.
+Scenario YAML is different — it describes transactions that flow forward.
+`acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so a scenario re-runs safely on a warm tenant.
+
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.14 or newer.
 
 ```sh
 uv tool install acumatica-cli
@@ -131,9 +122,9 @@ acu apply --dry-run    # show what would be written, write nothing
 `acu` talks to an instance over two independent channels:
 
 - **Control plane (SSH):** `acu tenant` runs `ac.exe -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see [`docs/ac-exe.md`](docs/ac-exe.md).
-- **Data plane (REST):** `acu apply`, `diff`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
+- **Data plane (REST):** `acu apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md).
 
-If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+If you never touch `acu tenant`, you never need SSH — every other command is pure REST.
 
 ## SSH setup (control plane)
 

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "acumatica-cli"
-version = "0.7.0"
+version = "0.8.1"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.14"
 dependencies = [
     "click>=8.1",
     "httpx>=0.27",
@@ -41,7 +41,7 @@ markers = [
 
 [tool.basedpyright]
 typeCheckingMode = "strict"
-pythonVersion = "3.12"
+pythonVersion = "3.14"
 include = ["src/acumatica_cli/", "tests/"]
 reportMissingTypeStubs = false
 reportUnknownVariableType = false
@@ -52,7 +52,7 @@ reportUnknownLambdaType = false
 reportUnusedFunction = "warning"
 
 [tool.ruff]
-target-version = "py312"
+target-version = "py314"
 src = ["src"]
 
 [tool.ruff.format]

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/bootstrap.py

@@ -150,7 +150,7 @@ def _published_description(client: AcumaticaClient) -> str | None:
     try:
         with zipfile.ZipFile(io.BytesIO(content)) as zf:
             root = ET.fromstring(zf.read("project.xml"))
-    except (zipfile.BadZipFile, KeyError, ET.ParseError):
+    except zipfile.BadZipFile, KeyError, ET.ParseError:
         return None
     return root.get("description")
 

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/bootstrap_project.xml

@@ -157,7 +157,12 @@
                 fields with no server default (read off the LAB5 PUT
                 2026-07-13): INProgressAcctID/INProgressSubID (the WIP
                 account) + the four reason codes (Issues/Receipt/
-                Adjustment/PI) - all exposed; HoldEntry = the echo flag.
+                Adjustment/PI) - all exposed; HoldEntry = the echo flag;
+                INTransitAcctID/INTransitSubID join once the Warehouse
+                feature is on (update 500s "'In-Transit Account' cannot
+                be empty", P5 probe); UpdateGL defaults OFF - released
+                IN documents move quantities but post no GL (COGS and
+                PO accrual sat at zero while revenue moved, P5 probe).
   - ReasonCode  CS211000 -> ReasonCodeMaint, PrimaryView reasoncode
                 (PX.Objects.CS.ReasonCode) - no Default-endpoint entity,
                 and the INSetup reason-code fields above hard-require
@@ -169,11 +174,18 @@
                 (ARSetup); HoldEntry echo field.
   - SOPreferences SO101000 -> SOSetupMaint, PrimaryView sosetup (SOSetup);
                 DefaultOrderType doubles as the echo field and the R1
-                probe (does order type SO pre-exist on an empty tenant).
+                probe (does order type SO pre-exist on an empty tenant);
+                HoldShipments/RequireShipmentTotal off + AutoReleaseIN on
+                keep the shipment->invoice chain scriptable (template
+                defaults park shipments On Hold and refuse confirmation
+                without a control total - P5 probes).
   - POPreferences PO101000 -> POSetupMaint, PrimaryView Setup (POSetup);
                 HoldReceipts echo field + RCReturnReasonCodeID (the one
                 POSetup field the live insert named as required - a
-                Vendor Return usage reason code, 2026-07-13).
+                Vendor Return usage reason code, 2026-07-13) +
+                AutoReleaseIN (default off: a released PO receipt leaves
+                its IN document Balanced and qty never lands on hand -
+                P5 probe).
   - AvailabilityCalculationRule IN201500 -> INAvailabilitySchemeMaint,
                 PrimaryView Schemes (INAvailabilityScheme) - an empty
                 tenant has zero scheme rows and ItemClass 422s
@@ -209,6 +221,23 @@
                 fixed-day-of-month choice; the AgeDays00-02 aging bounds
                 default inconsistently at raw insert ("end day earlier
                 than its start day" 422) so the seed supplies them.
+  - Warehouse   IN204000 -> INSiteMaint, PrimaryView site (DAC
+                PX.Objects.IN.INSite) - the Default Warehouse entity has
+                no address surface, and the auto-created warehouse
+                Address 422s "'Country' cannot be empty" at insert (P5
+                probe 2026-07-13; the T65 vendor class, but Default has
+                no path). SiteCD/Descr/Active on the primary view,
+                CountryID through the Address view.
+  - OrderType   SO201000 -> SOOrderTypeMaint, PrimaryView soordertype
+                (DAC PX.Objects.SO.SOOrderType) - no Default-endpoint
+                entity, and a fresh tenant has ZERO order-type rows
+                (they live in the template company, CompanyID 1,
+                Active=0 - sqlcmd-verified 2026-07-13): a SalesOrder
+                PUT answers 200 with an UNSAVED row (OrderNbr stays
+                <SELECT>, CustomerID silently empty) because numbering
+                never resolves. Keyed PUT on OrderType materializes the
+                template row into the tenant; Active activates it; the
+                freight pair is required at persist (422, no default).
   - CashAccount CA202000 -> CashAccountMaint, PrimaryView CashAccount
                 (PX.Objects.CA.CashAccount) - Default endpoint answers
                 404. CuryID stays out (derived from the GL account,
@@ -218,9 +247,9 @@
   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 + financial currency + GL preferences + ledger-company link + financial year + calendars + period activation + module preferences (IN/AP/AR/SO/PO) + availability rule + posting class + cash account + vendor class + statement cycle" product-version="26.101">
+<Customization level="" description="acu bootstrap: CustomizationPlugin enables features on publish; Bootstrap endpoint exposes company + credit terms + financial currency + GL preferences + ledger-company link + financial year + calendars + period activation + module preferences (IN/AP/AR/SO/PO) + availability rule + posting class + cash account + vendor class + statement cycle + warehouse + order type" product-version="26.101">
   <EntityEndpoint>
-    <Endpoint xmlns="http://www.acumatica.com/entity/maintenance/5.31" name="Bootstrap" version="1.6.0" systemContractVersion="4">
+    <Endpoint xmlns="http://www.acumatica.com/entity/maintenance/5.31" name="Bootstrap" version="1.7.0" systemContractVersion="4">
       <TopLevelEntity name="Company" screen="CS101500">
         <Fields>
           <Field name="AcctCD" type="StringValue" />
@@ -532,6 +561,9 @@
           <Field name="ReceiptReasonCode" type="StringValue" />
           <Field name="AdjustmentReasonCode" type="StringValue" />
           <Field name="PIReasonCode" type="StringValue" />
+          <Field name="INTransitAcctID" type="StringValue" />
+          <Field name="INTransitSubID" type="StringValue" />
+          <Field name="UpdateGL" type="BooleanValue" />
         </Fields>
         <Mappings>
           <Mapping field="HoldEntry">
@@ -555,6 +587,15 @@
           <Mapping field="PIReasonCode">
             <To object="setup" field="PIReasonCode" />
           </Mapping>
+          <Mapping field="INTransitAcctID">
+            <To object="setup" field="INTransitAcctID" />
+          </Mapping>
+          <Mapping field="INTransitSubID">
+            <To object="setup" field="INTransitSubID" />
+          </Mapping>
+          <Mapping field="UpdateGL">
+            <To object="setup" field="UpdateGL" />
+          </Mapping>
         </Mappings>
       </TopLevelEntity>
       <TopLevelEntity name="ReasonCode" screen="CS211000">
@@ -606,22 +647,38 @@
       <TopLevelEntity name="SOPreferences" screen="SO101000">
         <Fields>
           <Field name="DefaultOrderType" type="StringValue" />
+          <Field name="HoldShipments" type="BooleanValue" />
+          <Field name="RequireShipmentTotal" type="BooleanValue" />
+          <Field name="AutoReleaseIN" type="BooleanValue" />
         </Fields>
         <Mappings>
           <Mapping field="DefaultOrderType">
             <To object="sosetup" field="DefaultOrderType" />
           </Mapping>
+          <Mapping field="HoldShipments">
+            <To object="sosetup" field="HoldShipments" />
+          </Mapping>
+          <Mapping field="RequireShipmentTotal">
+            <To object="sosetup" field="RequireShipmentTotal" />
+          </Mapping>
+          <Mapping field="AutoReleaseIN">
+            <To object="sosetup" field="AutoReleaseIN" />
+          </Mapping>
         </Mappings>
       </TopLevelEntity>
       <TopLevelEntity name="POPreferences" screen="PO101000">
         <Fields>
           <Field name="HoldReceipts" type="BooleanValue" />
           <Field name="RCReturnReasonCodeID" type="StringValue" />
+          <Field name="AutoReleaseIN" type="BooleanValue" />
         </Fields>
         <Mappings>
           <Mapping field="HoldReceipts">
             <To object="Setup" field="HoldReceipts" />
           </Mapping>
+          <Mapping field="AutoReleaseIN">
+            <To object="Setup" field="AutoReleaseIN" />
+          </Mapping>
           <Mapping field="RCReturnReasonCodeID">
             <To object="Setup" field="RCReturnReasonCodeID" />
           </Mapping>
@@ -861,6 +918,50 @@
           </Mapping>
         </Mappings>
       </TopLevelEntity>
+      <TopLevelEntity name="Warehouse" screen="IN204000">
+        <Fields>
+          <Field name="SiteCD" type="StringValue" />
+          <Field name="Descr" type="StringValue" />
+          <Field name="Active" type="BooleanValue" />
+          <Field name="CountryID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="SiteCD">
+            <To object="site" field="SiteCD" />
+          </Mapping>
+          <Mapping field="Descr">
+            <To object="site" field="Descr" />
+          </Mapping>
+          <Mapping field="Active">
+            <To object="site" field="Active" />
+          </Mapping>
+          <Mapping field="CountryID">
+            <To object="Address" field="CountryID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
+      <TopLevelEntity name="OrderType" screen="SO201000">
+        <Fields>
+          <Field name="OrderType" type="StringValue" />
+          <Field name="Active" type="BooleanValue" />
+          <Field name="FreightAcctID" type="StringValue" />
+          <Field name="FreightSubID" type="StringValue" />
+        </Fields>
+        <Mappings>
+          <Mapping field="OrderType">
+            <To object="soordertype" field="OrderType" />
+          </Mapping>
+          <Mapping field="Active">
+            <To object="soordertype" field="Active" />
+          </Mapping>
+          <Mapping field="FreightAcctID">
+            <To object="soordertype" field="FreightAcctID" />
+          </Mapping>
+          <Mapping field="FreightSubID">
+            <To object="soordertype" field="FreightSubID" />
+          </Mapping>
+        </Mappings>
+      </TopLevelEntity>
       <TopLevelEntity name="CashAccount" screen="CA202000">
         <Fields>
           <Field name="CashAccountCD" type="StringValue" />

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/cli.py

@@ -379,12 +379,13 @@ def config_check(ctx: click.Context) -> None:
 
     Dependency order: discovery (.env walk-up + parse + ACU_BASE_URL), then
     secrets (ACU_PASSWORD resolved), then REST (login, landed-tenant verify,
-    logout) and ssh (trivial remote command) probed independently - a
-    discovery or secrets failure stops, a REST failure still probes ssh and
+    logout) and ssh probed independently - ssh set → trivial remote; ssh
+    unset → skip (ACU_SSH optional, V3 hosted path), never fail. A discovery
+    or secrets failure stops; a REST failure still probes ssh when set and
     vice versa. Discovery is lax (V3): no .env passes when --url covers
     base_url, and flags-only runs (no .env anywhere) are valid. Writes
-    nothing: no PUTs, no tenant CRUD. Exit 0 when every probe passes, 1 on
-    any failure.
+    nothing: no PUTs, no tenant CRUD. Exit 0 when every non-skipped probe
+    passes, 1 on any failure.
     """
     overrides: dict[str, str] = ctx.obj or {}
     # discovery (V3): lax walk-up + parse; base_url (the primary identity
@@ -432,12 +433,16 @@ def config_check(ctx: click.Context) -> None:
     except (RuntimeError, httpx.HTTPError) as exc:
         output.data(f"fail rest: {exc}")
         failed = True
-    try:
-        TenantManager(inst).ping()
-        output.data(f"ok ssh ({inst.ssh})")
-    except RuntimeError as exc:
-        output.data(f"fail ssh: {exc}")
-        failed = True
+    if not inst.ssh:
+        # V3/I.cmd: ACU_SSH optional — hosted data-plane path skips, never fails
+        output.data("skip ssh (ACU_SSH not set)")
+    else:
+        try:
+            TenantManager(inst).ping()
+            output.data(f"ok ssh ({inst.ssh})")
+        except RuntimeError as exc:
+            output.data(f"fail ssh: {exc}")
+            failed = True
     if failed:
         raise SystemExit(1)
 

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/client.py

@@ -94,7 +94,7 @@ class AcumaticaClient:
             base_url=instance.base_url, timeout=timeout, transport=transport
         )
 
-    def __enter__(self) -> "AcumaticaClient":
+    def __enter__(self) -> AcumaticaClient:
         # tenant guard (V5, docs/rest-api.md): an omitted or empty tenant is
         # the one login the server still routes silently — to the default
         # tenant. Defense-in-depth vs wrong-tenant writes: every data-plane

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/config.py

@@ -5,9 +5,10 @@ env prefix ``ACU_``, and the sole config file is ``.env`` (found by walking
 up from cwd) carrying where + secrets as ``ACU_*`` vars. The file is
 optional - flags plus the process environment can supply the full config.
 Per key the first set value wins: flag, ``ACU_*`` var (process environment
-over a found ``.env``), code default. ``base_url`` and ``ssh`` are the only
-required address values - one explicit address per plane (V1), never
-derived; the password must resolve via ``--password`` or ``ACU_PASSWORD``.
+over a found ``.env``), code default. ``base_url`` is the only required
+address (REST data plane); ``ssh`` is optional control-plane address
+(empty = data-plane only; tenant cmds hard-error when unresolved — V1/V3).
+The password must resolve via ``--password`` or ``ACU_PASSWORD``.
 """
 
 from collections.abc import Iterator, Mapping
@@ -51,11 +52,12 @@ INIT_TEMPLATES = (
 class Instance(BaseSettings):
     """The resolved target: flags over ACU_* vars (.env or process) over defaults.
 
-    One explicit address per plane (V1), no derivation: ``base_url`` is the
-    REST root (scheme + host + site path), ``ssh`` the control-plane
-    ``user@host``. Install-layout values are module constants, not fields.
-    Unknown ``ACU_*`` vars are ignored, never errors - the environment and
-    ``.env`` legitimately carry non-config vars (``ACU_DEBUG``).
+    Explicit addresses, no derivation (V1): ``base_url`` is the REST root
+    (scheme + host + site path); ``ssh`` is the optional control-plane
+    ``user@host`` (empty = data-plane only). Install-layout values are
+    module constants, not fields. Unknown ``ACU_*`` vars are ignored,
+    never errors - the environment and ``.env`` legitimately carry
+    non-config vars (``ACU_DEBUG``).
     """
 
     model_config = SettingsConfigDict(
@@ -65,7 +67,7 @@ class Instance(BaseSettings):
     )
 
     base_url: str  # REST root: scheme + host + site path
-    ssh: str  # control plane: full user@host
+    ssh: str = ""  # control plane: full user@host; empty = data-plane only
     tenant: str = ""
     api_version: str = "25.200.001"  # V11: /entity/Default/<api_version>/
     user: str = "admin"  # ACU_USER; the --username flag maps here
@@ -76,8 +78,8 @@ class Instance(BaseSettings):
     @model_validator(mode="before")
     @classmethod
     def _blank_required_is_unset(cls, data: Any) -> Any:
-        # a blank ACU_BASE_URL= / ACU_SSH= line reads as missing, not as an
-        # empty address - the hard error names the unresolved key (V3)
+        # blank ACU_BASE_URL= / ACU_SSH= reads as unset (V3): base_url then
+        # fails required; ssh falls through to the empty default (optional)
         if isinstance(data, dict):
             for key in ("base_url", "ssh"):
                 if data.get(key) == "":
@@ -161,8 +163,9 @@ def load_instance(overrides: Mapping[str, str | None] | None = None) -> Instance
     ``overrides`` carries the global flags keyed by Instance field name;
     per key the first set value wins (flag, ACU_* var - process environment
     over a found .env - code default). No .env is fine (V3): the hard error
-    comes only when a required value (base_url, ssh, password) is still
-    unresolved after the merge, naming the missing key.
+    comes only when a required value (base_url, password) is still
+    unresolved after the merge, naming the missing key. ``ssh`` is optional
+    (hosted / data-plane-only path); tenant cmds hard-error when it is empty.
     """
     flags = {k: v for k, v in dict(overrides or {}).items() if v is not None}
     root = find_data_root()

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/extract.py

@@ -66,7 +66,7 @@ class EntitySpec(Model):
         return BOOTSTRAP_ENDPOINT if v == "bootstrap" else v
 
     @model_validator(mode="after")
-    def _strip_include_exclusive(self) -> "EntitySpec":
+    def _strip_include_exclusive(self) -> EntitySpec:
         if self.strip and self.include:
             raise ValueError("strip and include are mutually exclusive")
         return self
@@ -96,7 +96,7 @@ class Manifest(Model):
     setup: list[SetupSynth] = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def _self_consistent(self) -> "Manifest":
+    def _self_consistent(self) -> Manifest:
         # V20 by construction: an emitted file for an entity both endpoints
         # serve must carry an endpoint, or load_baseline rejects it
         for spec in self.entities:

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/output.py

@@ -6,6 +6,7 @@ and spinners on a TTY and degrades to plain deterministic text when piped
 stderr carries status, warnings, and errors.
 """
 
+import os
 from collections.abc import Generator, Iterable
 from contextlib import contextmanager
 
@@ -13,8 +14,30 @@ from rich import box
 from rich.console import Console
 from rich.table import Table
 
-out = Console(markup=False, emoji=False, highlight=False)
-err = Console(stderr=True, markup=False, emoji=False, highlight=False)
+
+def _force_terminal() -> bool | None:
+    """Map NO_COLOR / FORCE_COLOR to rich's force_terminal flag.
+
+    None leaves auto-detect (isatty). False forces plain/piped rendering.
+    True forces TTY chrome even when piped.
+
+    Rich treats any non-empty FORCE_COLOR as "on", so FORCE_COLOR=0 would
+    otherwise enable color. We treat empty and "0" as off (force-color.org).
+    NO_COLOR (any value) always wins and forces plain output (no-color.org).
+    """
+    if "NO_COLOR" in os.environ:
+        return False
+    force = os.environ.get("FORCE_COLOR")
+    if force is not None:
+        return force not in ("", "0")
+    return None
+
+
+_force = _force_terminal()
+out = Console(markup=False, emoji=False, highlight=False, force_terminal=_force)
+err = Console(
+    stderr=True, markup=False, emoji=False, highlight=False, force_terminal=_force
+)
 
 
 def data(msg: str) -> None:

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/run.py

@@ -56,6 +56,7 @@ from .models import Model, validation_summary
 from .seed import _norm  # pyright: ignore[reportPrivateUsage]
 
 _VAR = re.compile(r"\$\{([A-Za-z0-9_]+)\}")
+_PATH = re.compile(r"([A-Za-z0-9_]+)(?:\[(\d+)\])?")
 
 
 class ActionSpec(Model):
@@ -75,31 +76,41 @@ class WaitSpec(Model):
     endpoint: str | None = None
 
 
+class GetOp(Model):
+    """Key-URL fetch a get step performs; expand pulls detail arrays."""
+
+    entity: str
+    keys: list[Any]
+    expand: list[str] | None = None
+    endpoint: str | None = None
+
+
 class Step(Model):
-    """One scenario step: exactly one op (put | action | wait-only)."""
+    """One scenario step: exactly one op (put | action | get | wait-only)."""
 
     id: str
     put: str | None = None
     action: ActionSpec | None = None
+    get: GetOp | None = None
     record: dict[str, Any] | None = None
     parameters: dict[str, Any] | None = None
-    capture: dict[str, str] | None = None  # {Field: var_name}
+    capture: dict[str, str] | None = None  # {Field-or-path: var_name}
     wait: WaitSpec | None = None
     endpoint: str | None = None
 
     @model_validator(mode="after")
-    def _one_op(self) -> "Step":
-        ops = [op for op in (self.put, self.action) if op is not None]
+    def _one_op(self) -> Step:
+        ops = [op for op in (self.put, self.action, self.get) if op is not None]
         if len(ops) > 1:
-            raise ValueError(f"step '{self.id}': put and action are exclusive")
+            raise ValueError(f"step '{self.id}': put, action, get are exclusive")
         if not ops and self.wait is None:
-            raise ValueError(f"step '{self.id}': needs one of put, action, wait")
+            raise ValueError(f"step '{self.id}': needs one of put, action, get, wait")
         if self.put is not None and self.record is None:
             raise ValueError(f"step '{self.id}': put needs a record")
         if self.action is not None and self.record is None:
             raise ValueError(f"step '{self.id}': action needs a record")
-        if self.capture is not None and self.put is None:
-            raise ValueError(f"step '{self.id}': capture rides a put step")
+        if self.capture is not None and self.put is None and self.get is None:
+            raise ValueError(f"step '{self.id}': capture rides a put or get step")
         return self
 
 
@@ -123,7 +134,7 @@ class Expect(Model):
     endpoint: str | None = None
 
     @model_validator(mode="after")
-    def _one_kind(self) -> "Expect":
+    def _one_kind(self) -> Expect:
         if (self.get is None) == (self.inquire is None):
             raise ValueError("expect: exactly one of get, inquire")
         if self.get is not None and self.fields is None:
@@ -153,7 +164,7 @@ class Scenario(Model):
     expect: list[Expect] = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def _unique_step_ids(self) -> "Scenario":
+    def _unique_step_ids(self) -> Scenario:
         seen: set[str] = set()
         for step in self.steps:
             if step.id in seen:
@@ -200,6 +211,34 @@ def _subst(value: Any, variables: dict[str, Any]) -> Any:
     return value
 
 
+def _resolve_path(record: dict[str, Any], path: str) -> Any:
+    """Resolve a dotted/indexed capture path (`Shipments[0].ShipmentNbr`).
+
+    Action-created documents (T66) assign numbers readable only off the
+    parent's expanded detail rows - the path walks unwrapped nesting:
+    a bare segment reads a field, `Seg[i]` indexes a detail array.
+    Missing segments raise with the path named.
+    """
+    value: Any = record
+    for segment in path.split("."):
+        m = _PATH.fullmatch(segment)
+        if m is None:
+            raise RuntimeError(f"capture path {path!r}: bad segment {segment!r}")
+        field, index = m.group(1), m.group(2)
+        if not isinstance(value, dict) or field not in value:
+            raise RuntimeError(
+                f"capture path {path!r}: field {field!r} not in the record"
+            )
+        value = value[field]
+        if index is not None:
+            if not isinstance(value, list) or int(index) >= len(value):
+                raise RuntimeError(
+                    f"capture path {path!r}: index [{index}] out of range"
+                )
+            value = value[int(index)]
+    return value
+
+
 def _inquire(client: AcumaticaClient, expect: Expect) -> dict[str, float]:
     """Probe a contract inquiry; sum each delta field over matching rows."""
     assert expect.inquire is not None
@@ -258,6 +297,8 @@ def _dry_run(scenario: Scenario) -> None:
             if step.put
             else f"invoke {step.action.entity}/{step.action.name}"
             if step.action
+            else f"get {step.get.entity}"
+            if step.get
             else f"wait {step.wait.entity}"  # pyright: ignore[reportOptionalMemberAccess]
         )
         output.data(f"  would {op} [{step.id}]")
@@ -290,6 +331,18 @@ def _run_step(client: AcumaticaClient, step: Step, variables: dict[str, Any]) ->
             step.endpoint,
         )
         output.data(f"  invoke {step.action.name} [{step.id}]")
+    elif step.get is not None:
+        keys = _subst(step.get.keys, variables)
+        params = (
+            {"$expand": ",".join(sorted(step.get.expand))} if step.get.expand else None
+        )
+        record = client.get_record(step.get.entity, keys, step.get.endpoint, params)
+        if record is None:
+            raise RuntimeError(f"step '{step.id}': {step.get.entity} {keys} not found")
+        fetched = unwrap(record)
+        output.data(f"  get {step.get.entity} [{step.id}]")
+        for path, var in (step.capture or {}).items():
+            variables[var] = _resolve_path(fetched, path)
     if step.wait is not None:
         _wait(client, step.wait, variables)
         output.data(f"  wait ok [{step.id}]")

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/seed.py

@@ -7,7 +7,7 @@ Baseline file format:
 
     entity: Currency          # entity name in the contract endpoint
     key: CurrencyID           # key field(s), string or list
-    endpoint: Bootstrap/1.6.0 # optional: override the instance endpoint
+    endpoint: Bootstrap/1.7.0 # optional: override the instance endpoint
     records:
       - CurrencyID: "CAD"
         Description: Canadian Dollar
@@ -34,7 +34,7 @@ cannot express (calendar generation and the like):
 
     action: GenerateCalendar          # action name on the endpoint entity
     entity: MasterCalendar            # entity the action hangs off
-    endpoint: Bootstrap/1.6.0         # optional: override the instance endpoint
+    endpoint: Bootstrap/1.7.0         # optional: override the instance endpoint
     record:     { FinancialYear: 2026 }
     parameters: { FromYear: 2026, ToYear: 2026 }   # optional
     done_when:  { filter: "FinancialYear eq '2026'" }
@@ -109,7 +109,7 @@ class BaselineFile(Model):
         return v if isinstance(v, list) else [v]
 
     @model_validator(mode="after")
-    def _keys_identify_records(self) -> "BaselineFile":
+    def _keys_identify_records(self) -> BaselineFile:
         # V25: the declared key tuple must uniquely identify records - a
         # dup-keyed file diffs as permanent false drift and apply collapses
         # the dup records into one PUT target (B21)

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/baseline/50-gl-preferences.yaml

@@ -1,4 +1,4 @@
-# General Ledger preferences (GL102000) via the custom Bootstrap/1.6.0
+# General Ledger preferences (GL102000) via the custom Bootstrap/1.7.0
 # endpoint (the per-file endpoint: override) - the Default endpoint has
 # no GL-setup entity, and every Finance screen throws
 # PXSetupNotEnteredException until the GLSetup singleton row exists. The
@@ -12,7 +12,7 @@
 # referenced here must exist.
 entity: GLPreferences
 key: RetEarnAccountID
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 records:
 - RetEarnAccountID: '32000'
   YtdNetIncAccountID: '33000'

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/baseline/60-ledger-company.yaml

@@ -1,4 +1,4 @@
-# Org-ledger link (GL201500) via the custom Bootstrap/1.6.0 endpoint (the
+# Org-ledger link (GL201500) via the custom Bootstrap/1.7.0 endpoint (the
 # per-file endpoint: override). The Default endpoint's Ledger.Companies
 # detail is write-tolerated then silently dropped (PUT answers 200 and
 # echoes the row, the link table stays empty), so the link writes through
@@ -21,7 +21,7 @@
 # (company.yaml).
 entity: LedgerCompany
 key: [LedgerCD, OrganizationID]
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 records:
 - LedgerCD: ACTUAL
   OrganizationID: COMPANY

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/bootstrap/company.yaml

@@ -1,11 +1,11 @@
-# Company (CS101500) via the custom Bootstrap/1.6.0 endpoint (the per-file
+# Company (CS101500) via the custom Bootstrap/1.7.0 endpoint (the per-file
 # endpoint: override) - built-in endpoints cannot create the first
 # organization on a virgin tenant. List values are the EXTERNAL labels
 # ('Without Branches', not the DAC's 'WithoutBranches'); CountryID feeds
 # the org's Main Address - required on first save.
 entity: Company
 key: AcctCD
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 records:
 - AcctCD: COMPANY
   AcctName: Example Company

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/bootstrap/credit-terms.yaml

@@ -1,11 +1,11 @@
-# Credit terms (CS206500) via the custom Bootstrap/1.6.0 endpoint (the
+# Credit terms (CS206500) via the custom Bootstrap/1.7.0 endpoint (the
 # per-file endpoint: override) - the Default endpoint has no credit-terms
 # entity. List values are the EXTERNAL labels: VisibleTo = All, Vendors,
 # Customers, Disabled; DueType/DiscType = Fixed Number of Days, Day of
 # Next Month, End of Month, ...
 entity: CreditTerms
 key: TermsID
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 records:
 - TermsID: NET30
   Descr: Net 30 Days

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/env

@@ -1,8 +1,9 @@
 # scaffolded by `acu config init` - the sole config file: where + secrets,
 # every key an ACU_* var; print the fully resolved document with:
 #   acu config show
-# ACU_BASE_URL (REST root) and ACU_SSH (control-plane user@host) are the
-# required addresses; the rest are code defaults you can override here.
+# ACU_BASE_URL (REST root) is required; ACU_SSH (control-plane user@host)
+# is optional - leave blank for hosted / data-plane-only (tenant CRUD still
+# needs it). The rest are code defaults you can override here.
 # Keep this file out of git (the scaffolded .gitignore already lists it;
 # encrypt at rest, e.g. .env.gpg).
 ACU_BASE_URL=http://erp.example.com/AcumaticaERP

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/setup/10-financial-year.yaml

@@ -19,7 +19,7 @@
 # generation consumes this setup row.
 action: GeneratePeriods
 entity: FinancialYearSettings
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 record:
   BegFinYear: "2026-01-01"
   FinPeriods: 12

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/setup/20-master-calendar.yaml

@@ -17,7 +17,7 @@
 # consumes the FinYearSetup row it creates.
 action: GenerateCalendar
 entity: MasterCalendar
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 record:
   FinancialYear: "2026"
 parameters:

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/templates/setup/30-open-periods.yaml

@@ -22,7 +22,7 @@
 # consumes the periods generation creates.
 action: ProcessAll
 entity: ManagePeriods
-endpoint: Bootstrap/1.6.0
+endpoint: Bootstrap/1.7.0
 record:
   Action: Open
   FromYear: "2026"

{acumatica_cli-0.7.0 → acumatica_cli-0.8.1}/src/acumatica_cli/tenant.py

@@ -28,6 +28,14 @@ class TenantManager:
     """Tenant CRUD via SSH to the Windows guest."""
 
     def __init__(self, instance: Instance):
+        # control-plane address is optional on Instance (hosted path, V3);
+        # tenant CRUD still needs it - hard-error naming the key before any
+        # remote (I.cmd), never an empty ssh argv
+        if not instance.ssh:
+            raise SystemExit(
+                "ACU_SSH not set (pass --ssh, "
+                "or put ACU_SSH in .env or the environment)"
+            )
         self.instance = instance
 
     def _ssh(self, command: str) -> str: