acumatica-cli 0.3.0__tar.gz → 0.4.0__tar.gz

acumatica_cli-0.4.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.3
+Name: acumatica-cli
+Version: 0.4.0
+Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
+Author: Konstantin Borovik
+Author-email: Konstantin Borovik <kb@lab5.ca>
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Python: >=3.12
+Project-URL: Homepage, https://lab5.ca
+Project-URL: Repository, https://github.com/kborovik/acumatica-cli
+Description-Content-Type: text/markdown
+
+# Acumatica Config-as-Code
+
+**`acu`** configures Acumatica ERP from YAML files in a git repo. 
+
+**No UI clicks, no Configuration Wizard.**
+
+## How it works
+
+1. **Read** the target Acumatica deployment and translate its configuration into 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`.
+
+Three 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.
+
+> **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.
+
+## Why
+
+Acumatica configuration normally lives in the web UI: wizards, screens, and manual data entry that nobody can review, version, or reproduce. 
+
+`acu` moves that configuration into YAML files in a git repo, so a tenant can be rebuilt from scratch, audited in a pull request, and checked for drift like any other infrastructure.
+
+## Quick start
+
+```sh
+uv tool install acumatica-cli
+
+acu config init --host erp.example.com my-erp
+cd my-erp                                # edit .env: set ACU_PASSWORD
+
+acu config check                         # read-only preflight
+acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+```
+
+## CLI map
+
+```text
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
+    [--username U] [--password P]
+│
+├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
+│   ├── list                          CompanyID, sign-in name, internal CD, type
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
+│   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
+│
+├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
+├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
+│
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved config as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
+```
+
+`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`. 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:
+
+| 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            |
+| `.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.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```sh
+uv tool install acumatica-cli
+```
+
+`pipx install acumatica-cli` and `pip install acumatica-cli` work too. For the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+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:
+
+```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             # required: control-plane user@host
+ACU_USER=admin                                         # optional, defaults to admin
+ACU_PASSWORD=...                                       # required
+```
+
+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.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the two address keys.
+- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded. Redirect it to turn resolved state into a working config: `acu config show > .env`.
+
+Verify before touching anything live:
+
+```sh
+acu config check       # read-only preflight: discovery, secrets, REST, SSH
+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 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).
+
+If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+
+## 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'
+```

acumatica_cli-0.4.0/README.md

@@ -0,0 +1,171 @@
+# Acumatica Config-as-Code
+
+**`acu`** configures Acumatica ERP from YAML files in a git repo. 
+
+**No UI clicks, no Configuration Wizard.**
+
+## How it works
+
+1. **Read** the target Acumatica deployment and translate its configuration into 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`.
+
+Three 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.
+
+> **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.
+
+## Why
+
+Acumatica configuration normally lives in the web UI: wizards, screens, and manual data entry that nobody can review, version, or reproduce. 
+
+`acu` moves that configuration into YAML files in a git repo, so a tenant can be rebuilt from scratch, audited in a pull request, and checked for drift like any other infrastructure.
+
+## Quick start
+
+```sh
+uv tool install acumatica-cli
+
+acu config init --host erp.example.com my-erp
+cd my-erp                                # edit .env: set ACU_PASSWORD
+
+acu config check                         # read-only preflight
+acu tenant create --id 3 --login DEV     # create the tenant + bootstrap it
+acu --tenant DEV apply                   # seed bootstrap/, baseline/, setup/
+acu --tenant DEV diff                    # prove zero drift (exit 2 on drift)
+```
+
+## CLI map
+
+```text
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
+    [--username U] [--password P]
+│
+├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
+│   ├── list                          CompanyID, sign-in name, internal CD, type
+│   ├── create --id N --login NAME    create + bootstrap; re-run to republish
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
+│   └── delete --id N [--yes]         delete the tenant and its data, recycle app pool
+│
+├── apply [--dry-run] [FILES...]      push YAML via REST (idempotent PUT upserts)
+├── diff  [FILES...]                  drift check vs the live tenant (exit 2 on drift)
+├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
+│
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved config as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
+```
+
+`apply` and `diff` called without FILES default to the scaffolded directories, in order: `bootstrap/`, then `baseline/`, then `setup/`. 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:
+
+| 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            |
+| `.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.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```sh
+uv tool install acumatica-cli
+```
+
+`pipx install acumatica-cli` and `pip install acumatica-cli` work too. For the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+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:
+
+```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             # required: control-plane user@host
+ACU_USER=admin                                         # optional, defaults to admin
+ACU_PASSWORD=...                                       # required
+```
+
+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.
+- Nothing is derived: split-horizon DNS, port forwards, and jump hosts are all handled by writing the address you actually want into the two address keys.
+- `acu config show` prints the fully resolved configuration as a complete, valid `.env` — every knob visible, the password excluded. Redirect it to turn resolved state into a working config: `acu config show > .env`.
+
+Verify before touching anything live:
+
+```sh
+acu config check       # read-only preflight: discovery, secrets, REST, SSH
+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 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).
+
+If you only apply and diff YAML, you never need SSH. SSH setup is required only for `acu tenant`.
+
+## 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'
+```

{acumatica_cli-0.3.0 → acumatica_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 readme = "README.md"

{acumatica_cli-0.3.0 → acumatica_cli-0.4.0}/src/acumatica_cli/cli.py

@@ -10,8 +10,9 @@ from typing import Concatenate
 
 import click
 import httpx
+from click.shell_completion import get_completion_class
 
-from . import bootstrap, firstlogin, output, seed
+from . import bootstrap, extract, firstlogin, output, seed
 from .client import AcumaticaClient
 from .config import (
     Instance,
@@ -43,8 +44,53 @@ def _version() -> str:
     return dist.version
 
 
+# flag_value sentinel: a bare --completion means "detect from $SHELL"
+_DETECT_SHELL = "auto"
+
+
+def _completion_script(shell: str) -> str:
+    """The click completion script for one supported shell (I.cmd --completion).
+
+    The _DETECT_SHELL sentinel resolves the shell from $SHELL's basename,
+    so a bare --completion works in the shell it runs in; an unsupported
+    or undetectable shell errors naming the supported set (V9: exit 1).
+    Emission is local-only (V23): click renders the script text, nothing
+    live is touched - enabling is the user's job (source the output).
+    """
+    if shell == _DETECT_SHELL:
+        shell = Path(os.environ.get("SHELL", "")).name
+    completion_cls = get_completion_class(shell)
+    if completion_cls is None:
+        raise SystemExit(
+            f"cannot emit completion for shell {shell!r} (supported: bash, zsh, fish)"
+        )
+    return completion_cls(cli, {}, "acu", "_ACU_COMPLETE").source()
+
+
+def _emit_completion(
+    ctx: click.Context, _param: click.Parameter, shell: str | None
+) -> None:
+    """Print the completion script and exit - eager, like --version (V16)."""
+    if shell is None or ctx.resilient_parsing:
+        return
+    output.data(_completion_script(shell))
+    ctx.exit()
+
+
 @click.group(help=__doc__)
 @click.version_option(version=_version(), prog_name="acu")
+@click.option(
+    "--completion",
+    is_flag=False,
+    flag_value=_DETECT_SHELL,
+    default=None,
+    expose_value=False,
+    is_eager=True,
+    callback=_emit_completion,
+    metavar="[bash|zsh|fish]",
+    help="Print the shell completion script and exit; a bare --completion "
+    "detects the shell from $SHELL. Enable by sourcing the output.",
+)
 @click.option(
     "--tenant",
     default=None,
@@ -160,8 +206,12 @@ def tenant_list(inst: Instance) -> None:
 @click.option(
     "--type",
     "company_type",
-    default="",
-    help="Inserted data set: '' = clean, SalesDemo = demo",
+    # the V12-verified dataset folders on the box (docs/ac-exe.md); System
+    # is the system-tenant dataset, deliberately not offered
+    type=click.Choice(["SalesDemo", "T100", "U100"]),
+    default=None,
+    help="Data set inserted at creation (omit for a clean tenant); "
+    "T100/U100 are the Acumatica University training sets",
 )
 @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")
@@ -175,7 +225,7 @@ def tenant_create(
     inst: Instance,
     company_id: int,
     login_name: str,
-    company_type: str,
+    company_type: str | None,
     parent_id: int,
     hidden: bool,
     no_init: bool,
@@ -211,8 +261,9 @@ def tenant_create(
         with output.step(
             f"creating tenant {company_id} ({login_name}) on {inst.base_url}"
         ):
+            # None = --type omitted = clean tenant (ac.exe's empty CompanyType)
             raw = mgr.create(
-                company_id, login_name, parent_id, not hidden, company_type
+                company_id, login_name, parent_id, not hidden, company_type or ""
             )
         output.data(raw.splitlines()[-1] if raw.strip() else "created")
     if no_init:
@@ -506,6 +557,70 @@ def diff_cmd(inst: Instance, files: tuple[Path, ...]) -> None:
     _exit_on_drift(inst, drifts, len(paths))
 
 
+def _complete_only(
+    _ctx: click.Context, _param: click.Parameter, incomplete: str
+) -> list[str]:
+    """--only value completion: entity names off the packaged manifest.
+
+    Fires per keystroke, so it stays local-only (V23): the manifest is
+    package data - never REST, never SSH, never a live instance.
+    """
+    return [
+        spec.entity
+        for spec in extract.load_manifest().entities
+        if spec.entity.startswith(incomplete)
+    ]
+
+
+@cli.command("extract")
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Output directory (default: current directory)",
+)
+@click.option(
+    "--only",
+    multiple=True,
+    shell_complete=_complete_only,
+    help="Limit to matching manifest rows (entity name or file stem); repeatable",
+)
+@click.option("--force", is_flag=True, help="Overwrite existing files")
+@click.option(
+    "--dry-run", is_flag=True, help="Show what would be written without writing"
+)
+@pass_instance
+def extract_cmd(
+    inst: Instance,
+    out_dir: Path | None,
+    only: tuple[str, ...],
+    force: bool,
+    dry_run: bool,
+) -> None:
+    """Extract live tenant state into seed YAML files (the inverse of apply).
+
+    Manifest-driven (the packaged extract manifest carries the verified
+    entity set): each entity is read from the live tenant and written as a
+    seed file under bootstrap/ or baseline/ that apply and diff consume
+    unchanged. Existing files are skipped unless --force; an entity with
+    no live records produces no file. A failing row is reported and the
+    run continues to the next (a virgin tenant extracts whole). Exit 0
+    when every row wrote or skipped clean, 1 when any row failed - drift
+    detection stays with diff.
+    """
+    with AcumaticaClient(inst) as client:
+        failed = extract.run(
+            client,
+            out_dir or Path("."),
+            only=frozenset(only),
+            force=force,
+            dry_run=dry_run,
+        )
+    if failed:
+        raise SystemExit(1)
+
+
 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:

{acumatica_cli-0.3.0 → acumatica_cli-0.4.0}/src/acumatica_cli/client.py

@@ -25,6 +25,20 @@ def unwrap(entity: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+# The list GET's optimized-export failure (B9): the contract API's list GET
+# 500s with this marker when any field in scope maps to a BQL-delegate view.
+# The one error read paths retry around (seed.diff via the key-URL GET,
+# extract via a $select-narrowed list GET); any other error still raises.
+OPTIMIZATION_500 = "Optimization cannot be performed"
+
+# The empty-state 500 extract classifies as a clean skip (V24): a virgin
+# tenant answers PXSetupNotEnteredException on most entities until bootstrap
+# lands, and the exceptionMessage names the missing form — "The required
+# configuration data is not entered on the <Form> form." (verified vs
+# 26.101.0225, docs/rest-api.md).
+SETUP_NOT_ENTERED_500 = "configuration data is not entered"
+
+
 class AcumaticaClient:
     """Cookie-session client for the contract-based endpoint.