acumatica-cli 0.15.3__tar.gz → 0.16.0__tar.gz

{acumatica_cli-0.15.3 → acumatica_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.15.3
+Version: 0.16.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -39,7 +39,7 @@ uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
 cd my-erp                                # edit .env: set ACU_PASSWORD, ACU_TENANT
-                                         # keep ACU_API_VERSION in sync with target.yaml
+                                         # Default API pin = target.yaml default_api
                                          # start from a brand-new empty tenant
 
 acu config check                         # read-only preflight (incl. target.yaml)
@@ -49,18 +49,17 @@ acu --tenant DEV apply config/           # seed config/{bootstrap,baseline,setup
 acu --tenant DEV run scenario/           # once capital → buy → build → sell
 acu --tenant DEV diff config/            # prove zero drift (exit 2 on drift)
 acu --tenant DEV state                   # capture state/ trial-balance
-# warm: capital once-skips; Owner Capital stays 50000 (not 100000)
-acu --tenant DEV run scenario/
+acu --tenant DEV run scenario/           # replay transaction scenarios
 ```
 
 Bare `apply` / `diff` (no path args) also prefer `config/` when those trees exist.
 See [docs/demo-seed.md](docs/demo-seed.md) for the entity map, once-guard, and apply-order notes.
 
-**Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
+**Hosted Acumatica (no SSH):** the tenant already exists; set a blank `ACU_SSH=` in `.env` (scaffold omits the key — without it, acu defaults to `Administrator@<ACU_BASE_URL host>` for SSH boxes).
 
 ```sh
 acu config init --host customer.acumatica.com my-erp
-cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
+cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; add ACU_SSH=
 acu config check                         # REST preflight; ssh probe is skipped
 acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
 acu --tenant DEV apply config/
@@ -89,6 +88,10 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
+├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
+│                                     offline snapshot artifact → inventory/ (not seed)
+├── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
+│                                     inventory/ + optional config/ → findings/ only
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
@@ -102,9 +105,28 @@ A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
 `state` without FILES defaults to `config/views/`; writes go to `state/` (`--out`).
 `extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
+`inventory` is offline (no REST/SSH/password): SM203520 Settings XML ZIP or `ac.exe export xml` folder writes to `inventory/`.
+`reconcile` is offline: compare `inventory/` to optional `config/` and write `findings/` only (never writes seed).
 `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.
 
+### Dual readers, one writer
+
+Two read paths, one mutator (V35).
+Do not confuse them with each other or with `state`:
+
+| Command | Plane | Input | Writes | Role |
+| ------- | ----- | ----- | ------ | ---- |
+| `extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
+| `inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
+| `reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
+| `state` | REST (live) | `config/views/` | `state/` | Derived balances/totals — not seed, not inventory |
+| `apply` | REST (live) | seed YAML under `config/` | tenant | **Sole** tenant writer (keyed PUT) |
+
+`inventory/` and `findings/` are engagement outputs: not SEED_DIRS, never loaded by `apply`/`diff`, not scaffolded by `config init`.
+Binary `.adb` snapshots are rejected (XML only).
+See [docs/ac-exe.md](docs/ac-exe.md) for export / SM203520 notes and [docs/demo-seed.md](docs/demo-seed.md) for the extract/state/inventory map.
+
 ## The data repo
 
 Your configuration lives in its own git repo.
@@ -120,13 +142,14 @@ There is no `--flavor`.
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
 | `config/views/` | observer views for `acu state` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
 | `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
+| `inventory/` | engagement: offline snapshot tables from `acu inventory` (not seed; not SEED_DIRS) |
+| `findings/` | engagement: `acu reconcile` cross-check output (never apply path) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
 Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
 
 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.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
@@ -141,38 +164,19 @@ git diff config/                           # review extract delta before commit
 acu --tenant DEV apply config/             # replay extracted seed
 acu --tenant DEV diff config/              # expect exit 0
 ```
-
-**Migration (T115–T120 extract hard-cut):** extract no longer writes root `bootstrap/` / `baseline/` / `setup/` / `master/`.
-Paths are always `config/…`.
-There is no `--layout`.
-Move any root-layout extract output under `config/`, or re-extract into a modern data repo.
-Catalog rename: `extract_manifest.yaml` becomes `seed_catalog.yaml` (package data only; operators do not author it).
-
-Scenario YAML is different — it describes transactions that flow forward (not extractable seed).
-`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 additive scenarios re-run safely on a warm tenant.
-`once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
-
-`acu state` is the third observation path: it captures live derived state (balances) into `state/` for git review.
-It is not `extract` (config seed) and not `diff` (desired vs actual config).
-Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`).
-After a cold `acu run scenario/ && acu state`, warm `acu run scenario/10-seed-capital.yaml && acu state --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
-
-**Migration (T112–T114 hard-cut):** CLI verb is `state` only (no `snapshot` alias).
-Bare defaults are `config/views/` (views) and `state/` (observations).
-Prior `config/snapshot/` and root `snapshot/` / `snapshots/` are not fallbacks — move views to `config/views/` or pass explicit path args.
-
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
 
 | Value | Resolves to |
 | ----- | ----------- |
-| omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
+| omitted | `Default/<api_version>` for Default-only entities |
 | `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
-| `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
-| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+| `default` | `Default/<api_version>` — tracks the resolved API version |
+| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores the resolved Default version) |
 
-Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
+`api_version` resolves as `--api-version` flag, else `target.yaml` `default_api` when present, else code default `25.200.001` (never `ACU_API_VERSION` in `.env`).
+Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the dataset pin.
 
 ## Installation
 
@@ -193,41 +197,45 @@ Verify with `acu --version`.
 
 ## Configuration
 
-Everything lives in one `.env` file: *where* to apply and *who* signs in.
-Three values are required; everything else has a code default matching a stock Acumatica install:
+Everything lives in one `.env` file: *where* to apply and *who* signs in
+(`ACU_*` vars only).
+The Default contract API pin is **not** in `.env` — it
+lives in committed `target.yaml` (`default_api`).
 
 ```sh
 ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
 ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
-ACU_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
-ACU_API_VERSION=25.200.001                             # Default contract version half only
+# ACU_SSH omitted → defaults to Administrator@acu-dev1.vm.internal
+# ACU_SSH=                                         # hosted opt-out (blank key)
 ACU_USER=admin                                         # optional, defaults to admin
 ACU_PASSWORD=...                                       # required for live commands
 ```
 
-`ACU_API_VERSION` is the version half only (`25.200.001`), never `Default/25.200.001`.
-A full path would nest as `/entity/Default/Default/...`.
+There is no `ACU_API_VERSION` env key (unknown `ACU_*` vars are ignored).
+Ad-hoc override: `acu --api-version 24.200.001 …` (version half only, never
+`Default/25.200.001` — a full path would nest as `/entity/Default/Default/...`).
 
-The committed `target.yaml` next to `.env` declares the verified matrix (what, not where):
+The committed `target.yaml` next to `.env` declares the verified matrix (what, not where) and is the **sole data-repo Default pin**:
 
 ```yaml
-erp: "26.101.0225"           # claimed product line/build (README-level detail)
-default_api: "25.200.001"    # must match ACU_API_VERSION
+erp: "26.101.0225"           # claimed product line/build
+default_api: "25.200.001"    # sources Instance.api_version when --api-version absent
 ```
 
-When `target.yaml` is present, `apply` / `diff` / `run` / `extract` / `schema` / `bootstrap` hard-fail if `default_api` does not match the configured API version.
-`acu config check` reports the same match as a probe line.
-Missing `target.yaml` only warns on check unless you pass `--strict`.
+When `target.yaml` is present, live commands resolve `api_version` from
+`default_api` (source-merge). `acu config check` reports
+`ok target (api_version from default_api=…; erp=… claimed)`.
+Missing `target.yaml` only warns on check unless you pass `--strict` (then
+the code default `25.200.001` is used).
 
 Worth knowing:
 
 - The file is found by walking up from the current directory, so any subdirectory of the data repo works.
 - Without a `.env`, global flags plus the process environment supply the full configuration.
-- `ACU_SSH` is optional.
-- Leave it blank on hosted instances; only `acu tenant` needs it.
-- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the address keys.
-- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded.
-- When `target.yaml` is present, `config show` also comments `erp` / `default_api`.
+- When `ACU_SSH` is **absent**, acu defaults to `Administrator@` + the `ACU_BASE_URL` hostname.
+  A **present blank** `ACU_SSH=` is the hosted opt-out.
+  Only `acu tenant` requires a non-empty value post-default.
+- `acu config show` prints the resolved `.env` (password excluded; never `ACU_API_VERSION`) and comments `erp` / `default_api` plus the `api_version` source when `target.yaml` is present.
 - Redirect it to turn resolved state into a working config: `acu config show > .env`.
 
 Verify before touching anything live:
@@ -238,65 +246,6 @@ acu config check --strict  # missing target.yaml becomes fail
 acu apply --dry-run        # show what would be written, write nothing
 ```
 
-## Control and Data Planes
-
-`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 bootstrap`, `apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API and CustomizationApi — see [`docs/rest-api.md`](docs/rest-api.md).
-
-If you never touch `acu tenant`, you never need SSH.
-On a hosted instance, publish AcuBootstrap with `acu bootstrap`, then seed with `apply`.
-`acu bootstrap --export PATH` writes the package zip for manual import on the Customization Projects screen (SM204505) when you cannot call the API.
-
-## SSH setup (control plane)
-
-`acu tenant` runs commands on the Windows guest through plain `ssh`.
-Two things about this setup are not obvious, and both are hard requirements.
-
-**1.
-The default SSH shell on the Windows guest must be PowerShell.**
-`acu` sends PowerShell syntax over the wire, and every one of those commands fails under `cmd.exe`, the Windows OpenSSH default.
-Switch it once, in an elevated PowerShell on the guest:
-
-```powershell
-New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell `
-  -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
-  -PropertyType String -Force
-```
-
-**2.
-Authentication must be key-based and non-interactive.**
-`acu` connects with `BatchMode=yes`, so it will never answer a password prompt.
-Because the default user is `Administrator` (an administrators-group member), Windows OpenSSH reads the key from the *machine-wide* file `C:\ProgramData\ssh\administrators_authorized_keys` — **not** from `~\.ssh\authorized_keys` like on Linux.
-On the guest:
-
-Install + start the server (once):
-
-```powershell
-Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-Set-Service sshd -StartupType Automatic
-Start-Service sshd
-```
-
-Authorize your public key for administrators:
-
-```powershell
-Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value "ssh-ed25519 AAAA... you@laptop"
-```
-
-The file must be readable by SYSTEM/Administrators only, or sshd ignores it:
-
-```powershell
-icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
-```
-
-Then verify from your workstation — this one test proves both requirements at once (key auth works, and the shell is PowerShell):
-
-```sh
-ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersion'
-```
-
 ## Development
 
 Requires **GNU Make at least 3.82** — the Makefile uses `.ONESHELL`.
@@ -328,7 +277,7 @@ GitHub Actions re-runs the check on the tag, then publishes the GitHub release a
 
 `gmake e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
 
-Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_SSH`, `ACU_TENANT`, `ACU_PASSWORD`.
+Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_TENANT`, `ACU_PASSWORD` (and optional `ACU_SSH`; omitted defaults to `Administrator@` + base-url host).
 `gmake e2e` refuses to start without it.
 
 The tier is self-contained.

{acumatica_cli-0.15.3 → acumatica_cli-0.16.0}/README.md

@@ -21,7 +21,7 @@ uv tool install acumatica-cli
 
 acu config init --host erp.example.com my-erp
 cd my-erp                                # edit .env: set ACU_PASSWORD, ACU_TENANT
-                                         # keep ACU_API_VERSION in sync with target.yaml
+                                         # Default API pin = target.yaml default_api
                                          # start from a brand-new empty tenant
 
 acu config check                         # read-only preflight (incl. target.yaml)
@@ -31,18 +31,17 @@ acu --tenant DEV apply config/           # seed config/{bootstrap,baseline,setup
 acu --tenant DEV run scenario/           # once capital → buy → build → sell
 acu --tenant DEV diff config/            # prove zero drift (exit 2 on drift)
 acu --tenant DEV state                   # capture state/ trial-balance
-# warm: capital once-skips; Owner Capital stays 50000 (not 100000)
-acu --tenant DEV run scenario/
+acu --tenant DEV run scenario/           # replay transaction scenarios
 ```
 
 Bare `apply` / `diff` (no path args) also prefer `config/` when those trees exist.
 See [docs/demo-seed.md](docs/demo-seed.md) for the entity map, once-guard, and apply-order notes.
 
-**Hosted Acumatica (no SSH):** the tenant already exists; leave `ACU_SSH` blank.
+**Hosted Acumatica (no SSH):** the tenant already exists; set a blank `ACU_SSH=` in `.env` (scaffold omits the key — without it, acu defaults to `Administrator@<ACU_BASE_URL host>` for SSH boxes).
 
 ```sh
 acu config init --host customer.acumatica.com my-erp
-cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; ACU_SSH=
+cd my-erp                                # edit .env: ACU_TENANT, ACU_PASSWORD; add ACU_SSH=
 acu config check                         # REST preflight; ssh probe is skipped
 acu --tenant DEV bootstrap               # publish AcuBootstrap via REST only
 acu --tenant DEV apply config/
@@ -71,6 +70,10 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 │                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
 │                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
+├── inventory [--out DIR] [--force] [--dry-run] ARTIFACT
+│                                     offline snapshot artifact → inventory/ (not seed)
+├── reconcile [--inventory DIR] [--config DIR] [--out DIR] [--force] [--dry-run]
+│                                     inventory/ + optional config/ → findings/ only
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
@@ -84,9 +87,28 @@ A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
 `state` without FILES defaults to `config/views/`; writes go to `state/` (`--out`).
 `extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
+`inventory` is offline (no REST/SSH/password): SM203520 Settings XML ZIP or `ac.exe export xml` folder writes to `inventory/`.
+`reconcile` is offline: compare `inventory/` to optional `config/` and write `findings/` only (never writes seed).
 `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.
 
+### Dual readers, one writer
+
+Two read paths, one mutator (V35).
+Do not confuse them with each other or with `state`:
+
+| Command | Plane | Input | Writes | Role |
+| ------- | ----- | ----- | ------ | ---- |
+| `extract` | REST (live) | tenant via contract API | `config/{bootstrap,baseline,setup,master}/` | Inverse of `apply` — seed YAML |
+| `inventory` | Offline | SM203520 Settings XML ZIP or `ac.exe export xml` folder | `inventory/` (`summary.yaml` + `tables/`) | Full-table snapshot IR — not seed |
+| `reconcile` | Offline | `inventory/` + optional `config/` | `findings/` only | Cross-check gaps/deltas — never mutates seed or tenant |
+| `state` | REST (live) | `config/views/` | `state/` | Derived balances/totals — not seed, not inventory |
+| `apply` | REST (live) | seed YAML under `config/` | tenant | **Sole** tenant writer (keyed PUT) |
+
+`inventory/` and `findings/` are engagement outputs: not SEED_DIRS, never loaded by `apply`/`diff`, not scaffolded by `config init`.
+Binary `.adb` snapshots are rejected (XML only).
+See [docs/ac-exe.md](docs/ac-exe.md) for export / SM203520 notes and [docs/demo-seed.md](docs/demo-seed.md) for the extract/state/inventory map.
+
 ## The data repo
 
 Your configuration lives in its own git repo.
@@ -102,13 +124,14 @@ There is no `--flavor`.
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
 | `config/views/` | observer views for `acu state` (`inquire:` / `entity:` / `gi:`; not SEED_DIRS) |
 | `state/` | committed derived-state observations (evidence, not seed; money/qty fixed-point) |
+| `inventory/` | engagement: offline snapshot tables from `acu inventory` (not seed; not SEED_DIRS) |
+| `findings/` | engagement: `acu reconcile` cross-check output (never apply path) |
 | `target.yaml` | committed verified matrix: `erp` + `default_api` (what, not where) |
 | `.env` | where to apply and who signs in, every key an `ACU_*` variable |
 
 Legacy data repos may still keep root `bootstrap/`…`master/`; bare `apply`/`diff` prefer `config/` when present and never merge both trees.
 
 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.
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
@@ -123,38 +146,19 @@ git diff config/                           # review extract delta before commit
 acu --tenant DEV apply config/             # replay extracted seed
 acu --tenant DEV diff config/              # expect exit 0
 ```
-
-**Migration (T115–T120 extract hard-cut):** extract no longer writes root `bootstrap/` / `baseline/` / `setup/` / `master/`.
-Paths are always `config/…`.
-There is no `--layout`.
-Move any root-layout extract output under `config/`, or re-extract into a modern data repo.
-Catalog rename: `extract_manifest.yaml` becomes `seed_catalog.yaml` (package data only; operators do not author it).
-
-Scenario YAML is different — it describes transactions that flow forward (not extractable seed).
-`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 additive scenarios re-run safely on a warm tenant.
-`once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
-
-`acu state` is the third observation path: it captures live derived state (balances) into `state/` for git review.
-It is not `extract` (config seed) and not `diff` (desired vs actual config).
-Packaged golden is trial-balance via contract `inquire:` (`EndingBalance` fixed-point); inventory-summary is not golden this pass. `gi:` stays optional when a GI is V12-verified and **Expose via OData** is on (`params` fail-closed vs `$metadata`).
-After a cold `acu run scenario/ && acu state`, warm `acu run scenario/10-seed-capital.yaml && acu state --assert-unchanged` is the once-class gate (full scenario re-run is additive and moves cash observations on the TB).
-
-**Migration (T112–T114 hard-cut):** CLI verb is `state` only (no `snapshot` alias).
-Bare defaults are `config/views/` (views) and `state/` (observations).
-Prior `config/snapshot/` and root `snapshot/` / `snapshots/` are not fallbacks — move views to `config/views/` or pass explicit path args.
-
 ### Seed `endpoint:` symbols
 
 Dual-served entities (on both Bootstrap and Default) need an explicit `endpoint:` line.
 
 | Value | Resolves to |
 | ----- | ----------- |
-| omitted | `Default/<ACU_API_VERSION>` for Default-only entities |
+| omitted | `Default/<api_version>` for Default-only entities |
 | `bootstrap` | active `Bootstrap/<ver>` from `bootstrap/project.xml` or the packaged contract |
-| `default` | `Default/<ACU_API_VERSION>` — tracks the operator API version |
-| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores `ACU_API_VERSION` for Default) |
+| `default` | `Default/<api_version>` — tracks the resolved API version |
+| `Bootstrap/1.0.0` or `Default/25.200.001` | literal pin (ignores the resolved Default version) |
 
-Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the configured API generation.
+`api_version` resolves as `--api-version` flag, else `target.yaml` `default_api` when present, else code default `25.200.001` (never `ACU_API_VERSION` in `.env`).
+Prefer symbolic `default` over a pinned `Default/25.200.001` so the seed tree travels with the dataset pin.
 
 ## Installation
 
@@ -175,41 +179,45 @@ Verify with `acu --version`.
 
 ## Configuration
 
-Everything lives in one `.env` file: *where* to apply and *who* signs in.
-Three values are required; everything else has a code default matching a stock Acumatica install:
+Everything lives in one `.env` file: *where* to apply and *who* signs in
+(`ACU_*` vars only).
+The Default contract API pin is **not** in `.env` — it
+lives in committed `target.yaml` (`default_api`).
 
 ```sh
 ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP  # required: REST root
 ACU_TENANT=LAB5                                        # sign-in name of the tenant API sessions use
-ACU_SSH=Administrator@acu-dev1.vm.internal             # optional: control-plane user@host (tenant CRUD)
-ACU_API_VERSION=25.200.001                             # Default contract version half only
+# ACU_SSH omitted → defaults to Administrator@acu-dev1.vm.internal
+# ACU_SSH=                                         # hosted opt-out (blank key)
 ACU_USER=admin                                         # optional, defaults to admin
 ACU_PASSWORD=...                                       # required for live commands
 ```
 
-`ACU_API_VERSION` is the version half only (`25.200.001`), never `Default/25.200.001`.
-A full path would nest as `/entity/Default/Default/...`.
+There is no `ACU_API_VERSION` env key (unknown `ACU_*` vars are ignored).
+Ad-hoc override: `acu --api-version 24.200.001 …` (version half only, never
+`Default/25.200.001` — a full path would nest as `/entity/Default/Default/...`).
 
-The committed `target.yaml` next to `.env` declares the verified matrix (what, not where):
+The committed `target.yaml` next to `.env` declares the verified matrix (what, not where) and is the **sole data-repo Default pin**:
 
 ```yaml
-erp: "26.101.0225"           # claimed product line/build (README-level detail)
-default_api: "25.200.001"    # must match ACU_API_VERSION
+erp: "26.101.0225"           # claimed product line/build
+default_api: "25.200.001"    # sources Instance.api_version when --api-version absent
 ```
 
-When `target.yaml` is present, `apply` / `diff` / `run` / `extract` / `schema` / `bootstrap` hard-fail if `default_api` does not match the configured API version.
-`acu config check` reports the same match as a probe line.
-Missing `target.yaml` only warns on check unless you pass `--strict`.
+When `target.yaml` is present, live commands resolve `api_version` from
+`default_api` (source-merge). `acu config check` reports
+`ok target (api_version from default_api=…; erp=… claimed)`.
+Missing `target.yaml` only warns on check unless you pass `--strict` (then
+the code default `25.200.001` is used).
 
 Worth knowing:
 
 - The file is found by walking up from the current directory, so any subdirectory of the data repo works.
 - Without a `.env`, global flags plus the process environment supply the full configuration.
-- `ACU_SSH` is optional.
-- Leave it blank on hosted instances; only `acu tenant` needs it.
-- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the address keys.
-- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded.
-- When `target.yaml` is present, `config show` also comments `erp` / `default_api`.
+- When `ACU_SSH` is **absent**, acu defaults to `Administrator@` + the `ACU_BASE_URL` hostname.
+  A **present blank** `ACU_SSH=` is the hosted opt-out.
+  Only `acu tenant` requires a non-empty value post-default.
+- `acu config show` prints the resolved `.env` (password excluded; never `ACU_API_VERSION`) and comments `erp` / `default_api` plus the `api_version` source when `target.yaml` is present.
 - Redirect it to turn resolved state into a working config: `acu config show > .env`.
 
 Verify before touching anything live:
@@ -220,65 +228,6 @@ acu config check --strict  # missing target.yaml becomes fail
 acu apply --dry-run        # show what would be written, write nothing
 ```
 
-## Control and Data Planes
-
-`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 bootstrap`, `apply`, `diff`, `run`, `extract`, and `schema` use the contract-based API and CustomizationApi — see [`docs/rest-api.md`](docs/rest-api.md).
-
-If you never touch `acu tenant`, you never need SSH.
-On a hosted instance, publish AcuBootstrap with `acu bootstrap`, then seed with `apply`.
-`acu bootstrap --export PATH` writes the package zip for manual import on the Customization Projects screen (SM204505) when you cannot call the API.
-
-## SSH setup (control plane)
-
-`acu tenant` runs commands on the Windows guest through plain `ssh`.
-Two things about this setup are not obvious, and both are hard requirements.
-
-**1.
-The default SSH shell on the Windows guest must be PowerShell.**
-`acu` sends PowerShell syntax over the wire, and every one of those commands fails under `cmd.exe`, the Windows OpenSSH default.
-Switch it once, in an elevated PowerShell on the guest:
-
-```powershell
-New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell `
-  -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
-  -PropertyType String -Force
-```
-
-**2.
-Authentication must be key-based and non-interactive.**
-`acu` connects with `BatchMode=yes`, so it will never answer a password prompt.
-Because the default user is `Administrator` (an administrators-group member), Windows OpenSSH reads the key from the *machine-wide* file `C:\ProgramData\ssh\administrators_authorized_keys` — **not** from `~\.ssh\authorized_keys` like on Linux.
-On the guest:
-
-Install + start the server (once):
-
-```powershell
-Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-Set-Service sshd -StartupType Automatic
-Start-Service sshd
-```
-
-Authorize your public key for administrators:
-
-```powershell
-Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value "ssh-ed25519 AAAA... you@laptop"
-```
-
-The file must be readable by SYSTEM/Administrators only, or sshd ignores it:
-
-```powershell
-icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
-```
-
-Then verify from your workstation — this one test proves both requirements at once (key auth works, and the shell is PowerShell):
-
-```sh
-ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersion'
-```
-
 ## Development
 
 Requires **GNU Make at least 3.82** — the Makefile uses `.ONESHELL`.
@@ -310,7 +259,7 @@ GitHub Actions re-runs the check on the tag, then publishes the GitHub release a
 
 `gmake e2e` runs the opt-in live tier against a real Acumatica instance (pytest marker `e2e`, deselected by the default suite).
 
-Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_SSH`, `ACU_TENANT`, `ACU_PASSWORD`.
+Configuration is one file: a decrypted `.env` at the repo root names the instance — `ACU_BASE_URL`, `ACU_TENANT`, `ACU_PASSWORD` (and optional `ACU_SSH`; omitted defaults to `Administrator@` + base-url host).
 `gmake e2e` refuses to start without it.
 
 The tier is self-contained.

acumatica_cli-0.16.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "acumatica-cli"
+version = "0.16.0"
+description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
+license = "PolyForm-Noncommercial-1.0.0"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.5",
+    "pyyaml>=6.0",
+    "rich>=13",
+]
+
+[[project.authors]]
+name = "Konstantin Borovik"
+email = "kb@lab5.ca"
+
+[project.urls]
+Homepage = "https://lab5.ca"
+Repository = "https://github.com/kborovik/acumatica-cli"
+
+[project.scripts]
+acu = "acumatica_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.37.0",
+    "pytest>=8",
+    "ruff>=0.13.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = '-q -m "not e2e"'
+markers = ["e2e: live end-to-end tests against a real Acumatica instance (make e2e)"]
+
+[tool.basedpyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+include = [
+    "src/acumatica_cli/",
+    "tests/",
+]
+reportMissingTypeStubs = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownLambdaType = false
+reportUnusedFunction = "warning"
+
+[tool.ruff]
+target-version = "py314"
+src = ["src"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = [
+    "B",
+    "C4",
+    "C90",
+    "COM",
+    "D",
+    "E",
+    "F",
+    "I",
+    "N",
+    "PL",
+    "PT",
+    "RUF",
+    "SIM",
+    "T20",
+    "TID",
+    "UP",
+    "W",
+]
+ignore = [
+    "PLR2004",
+    "PLC0415",
+    "D100",
+    "D104",
+    "D105",
+    "D107",
+    "COM812",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["acumatica_cli"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/acumatica_cli/cli.py" = ["PLR0913"]
+"tests/*" = [
+    "D101",
+    "D102",
+    "D103",
+]