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

{acumatica_cli-0.2.2 → acumatica_cli-0.3.0}/PKG-INFO

@@ -1,16 +1,18 @@
 Metadata-Version: 2.3
 Name: acumatica-cli
-Version: 0.2.2
-Summary: The acu CLI - Acumatica ERP configuration as code: tenant provisioning, baseline config, and reference data
+Version: 0.3.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: python-dotenv>=1.0
+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 CLI
@@ -22,8 +24,13 @@ Every operation is idempotent:
 
 - `acu apply` upserts records by key — running it twice is safe
 - `acu diff` detects drift between your YAML and the live tenant
-- `acu provision` takes an empty instance to a fully configured tenant in
-  one command, and skips every step that is already done
+- `acu tenant create` bootstraps the new tenant at birth, so it is ready
+  for `acu apply` in one step
+
+> **Development environment.** All development and live verification is done
+> against Acumatica ERP **26.101.0225** running on **Windows Server 2025**,
+> using the contract-based REST API endpoint **`Default/25.200.001`**. Other
+> versions will likely work, but only this combination is tested.
 
 ## Why?
 
@@ -42,80 +49,126 @@ acu config show     # sanity-check the resolved target
 ```
 
 ```sh
-acu provision --id 3 --login DEV        # create → bootstrap → apply → diff
-acu diff baseline/                      # later: prove zero drift (exit 2 on drift)
+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 [-t TENANT]
-│
-├── provision --id N --login NAME     one command: create → bootstrap → apply → diff
-│             [--type SalesDemo] [--parent N]
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--username U] [--password P]
 │
 ├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
 │   ├── list                          CompanyID, sign-in name, internal CD, type
-│   ├── create                        create a tenant and make it automation-ready
+│   ├── create --id N --login NAME    create a tenant + bootstrap it, ready to apply
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
 │   └── delete                        delete a tenant and its data, recycle app pool
 │
 ├── apply [--dry-run] FILES...        seed baseline YAML via REST (idempotent PUT upserts)
 ├── diff FILES...                     drift check: YAML vs live tenant (exit 2 on drift)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
-└── config                            local, read-only — never talks to a live instance
-    └── show                          print the resolved target as a complete acu.yaml
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved target as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
 ```
 
-The target instance comes from `acu.yaml` (found by walking up from the
-current directory); the one global option `-t/--tenant` overrides the tenant
-that API sessions sign in to. Run `acu <command> --help` for details on any
-command.
+The target instance comes from `.env` (found by walking up from the
+current directory), every key an `ACU_*` variable; global options
+(`--tenant`, `--url`, `--ssh`, `--api-version`, `--username`,
+`--password`) override per key. Run `acu <command> --help` for details on
+any command.
 
 ## Installation
 
-## Configuration
+`acu` requires Python 3.12 or newer. Pick one of the options below — each
+code block is a complete, standalone command.
 
-Configuration is split into three layers, each answering one question:
+### From PyPI (recommended)
 
-1. **`acu.yaml`** — *where* to apply. The whole file is the target
-   instance: a flat map where `host` is the only required key; everything
-   else has a code default matching a stock Acumatica install:
+With [uv](https://docs.astral.sh/uv/), installed as an isolated tool:
 
-   ```yaml
-   host: acu-dev1.vm.internal
-   tenant: Company     # sign-in name of the tenant API sessions use
-   ```
+```sh
+uv tool install acumatica-cli
+```
+
+With pipx:
+
+```sh
+pipx install acumatica-cli
+```
+
+With plain pip:
+
+```sh
+pip install acumatica-cli
+```
 
-   Optional overrides (defaults shown) for nonstandard installs,
-   split-horizon DNS, port forwards, or jump hosts:
+### From the GitHub repository
 
-   `acu config show` prints the fully resolved instance as a complete,
-   valid `acu.yaml` — every knob visible, credentials excluded. To turn
-   the resolved state into your working config, redirect and edit:
+Install the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Or with pip:
+
+```sh
+pip install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Verify the installation:
+
+```sh
+acu --help
+```
+
+## Configuration
+
+Configuration lives in one file plus your SSH setup:
+
+1. **`.env`** — the whole configuration: *where* to apply and *who* signs
+   in, every key an `ACU_*` variable. Three values are required —
+   `ACU_BASE_URL` (the REST root: scheme, host, and site path), `ACU_SSH`
+   (the control-plane `user@host`), and `ACU_PASSWORD`. Everything else
+   has a code default matching a stock Acumatica install:
 
    ```sh
-   acu config show > acu.yaml
+   ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP
+   ACU_SSH=Administrator@acu-dev1.vm.internal
+   ACU_TENANT=Company    # sign-in name of the tenant API sessions use
+   ACU_USER=admin        # optional, defaults to admin
+   ACU_PASSWORD=...      # required
    ```
 
-2. **`.env`** — *who* signs in to the REST API. Loaded from the data-repo
-   root (or the plain environment):
+   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. 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
+   config. The data repo stores the file encrypted as `.env.gpg`;
+   `make decrypt` produces the plaintext `.env` once per clone.
+
+   `acu config show` prints the fully resolved configuration as a
+   complete, valid `.env` — every knob visible, the password excluded.
+   To turn the resolved state into your working config, redirect and
+   edit:
 
    ```sh
-   ACU_PASSWORD=...    # required
-   ACU_USER=admin      # optional, defaults to admin
+   acu config show > .env
    ```
 
-   The data repo stores it encrypted as `.env.gpg`; `make decrypt` produces
-   the plaintext `.env` once per clone.
-
-3. **SSH** — *how* the control plane reaches the Windows guest. Configured on
-   the guest and in your `~/.ssh`, not in `acu.yaml` — see the next section.
+2. **SSH** — *how* the control plane reaches the Windows guest. Configured on
+   the guest and in your `~/.ssh`, not in `.env` — see the next section.
 
 Verify the result before touching anything live:
 
 ```sh
-acu config show           # the fully resolved instance as acu.yaml, no secrets
+acu config check          # read-only preflight: discovery, secrets, REST, SSH
+acu config show           # the fully resolved configuration as .env, no secrets
 acu apply --dry-run baseline/
 ```
 
@@ -125,19 +178,18 @@ acu apply --dry-run baseline/
 
 - **Control plane (SSH):** tenant create/delete/list via `ac.exe
   -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see
-  [`docs/ac-exe.md`](docs/ac-exe.md). Used by `acu tenant` and the first step
-  of `acu provision`.
+  [`docs/ac-exe.md`](docs/ac-exe.md). Used by `acu tenant`.
 - **Data plane (REST):** baseline configuration and reference data through
   the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a
   keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md). Used by
   `acu apply`, `acu diff`, and `acu schema`.
 
 If you only apply and diff baseline YAML, you never need SSH. SSH setup is
-required only for `acu tenant` and `acu provision`.
+required only for `acu tenant`.
 
 ## SSH setup (control plane)
 
-`acu tenant` and `acu provision` run commands on the Windows guest through
+`acu tenant` runs commands on the Windows guest through
 plain `ssh`. Two things about this setup are not obvious, and both are hard
 requirements:
 
@@ -184,4 +236,4 @@ ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersi
 A version table means you are ready; a password prompt or
 `'$PSVersionTable.PSVersion' is not recognized...` means requirement 2 or 1
 (respectively) is not met yet. Host aliases, jump hosts, and ports go in your
-`~/.ssh/config` as usual, or set `ssh: user@alias` in `acu.yaml`.
+`~/.ssh/config` as usual, or set `ACU_SSH=user@alias` in `.env`.

{acumatica_cli-0.2.2 → acumatica_cli-0.3.0}/README.md

@@ -7,8 +7,13 @@ Every operation is idempotent:
 
 - `acu apply` upserts records by key — running it twice is safe
 - `acu diff` detects drift between your YAML and the live tenant
-- `acu provision` takes an empty instance to a fully configured tenant in
-  one command, and skips every step that is already done
+- `acu tenant create` bootstraps the new tenant at birth, so it is ready
+  for `acu apply` in one step
+
+> **Development environment.** All development and live verification is done
+> against Acumatica ERP **26.101.0225** running on **Windows Server 2025**,
+> using the contract-based REST API endpoint **`Default/25.200.001`**. Other
+> versions will likely work, but only this combination is tested.
 
 ## Why?
 
@@ -27,80 +32,126 @@ acu config show     # sanity-check the resolved target
 ```
 
 ```sh
-acu provision --id 3 --login DEV        # create → bootstrap → apply → diff
-acu diff baseline/                      # later: prove zero drift (exit 2 on drift)
+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 [-t TENANT]
-│
-├── provision --id N --login NAME     one command: create → bootstrap → apply → diff
-│             [--type SalesDemo] [--parent N]
+acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--username U] [--password P]
 │
 ├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
 │   ├── list                          CompanyID, sign-in name, internal CD, type
-│   ├── create                        create a tenant and make it automation-ready
+│   ├── create --id N --login NAME    create a tenant + bootstrap it, ready to apply
+│   │          [--type SalesDemo] [--parent N] [--hidden] [--no-init]
 │   └── delete                        delete a tenant and its data, recycle app pool
 │
 ├── apply [--dry-run] FILES...        seed baseline YAML via REST (idempotent PUT upserts)
 ├── diff FILES...                     drift check: YAML vs live tenant (exit 2 on drift)
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
-└── config                            local, read-only — never talks to a live instance
-    └── show                          print the resolved target as a complete acu.yaml
+└── config                            configuration ops
+    ├── init [--host HOST] [DIR]      scaffold a data repo (.env plus example YAML)
+    ├── show                          print the resolved target as a complete .env
+    └── check                         read-only preflight: discovery, secrets, REST, SSH
 ```
 
-The target instance comes from `acu.yaml` (found by walking up from the
-current directory); the one global option `-t/--tenant` overrides the tenant
-that API sessions sign in to. Run `acu <command> --help` for details on any
-command.
+The target instance comes from `.env` (found by walking up from the
+current directory), every key an `ACU_*` variable; global options
+(`--tenant`, `--url`, `--ssh`, `--api-version`, `--username`,
+`--password`) override per key. Run `acu <command> --help` for details on
+any command.
 
 ## Installation
 
-## Configuration
+`acu` requires Python 3.12 or newer. Pick one of the options below — each
+code block is a complete, standalone command.
 
-Configuration is split into three layers, each answering one question:
+### From PyPI (recommended)
 
-1. **`acu.yaml`** — *where* to apply. The whole file is the target
-   instance: a flat map where `host` is the only required key; everything
-   else has a code default matching a stock Acumatica install:
+With [uv](https://docs.astral.sh/uv/), installed as an isolated tool:
 
-   ```yaml
-   host: acu-dev1.vm.internal
-   tenant: Company     # sign-in name of the tenant API sessions use
-   ```
+```sh
+uv tool install acumatica-cli
+```
+
+With pipx:
+
+```sh
+pipx install acumatica-cli
+```
+
+With plain pip:
+
+```sh
+pip install acumatica-cli
+```
 
-   Optional overrides (defaults shown) for nonstandard installs,
-   split-horizon DNS, port forwards, or jump hosts:
+### From the GitHub repository
 
-   `acu config show` prints the fully resolved instance as a complete,
-   valid `acu.yaml` — every knob visible, credentials excluded. To turn
-   the resolved state into your working config, redirect and edit:
+Install the latest development version straight from the main branch:
+
+```sh
+uv tool install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Or with pip:
+
+```sh
+pip install git+https://github.com/kborovik/acumatica-cli.git
+```
+
+Verify the installation:
+
+```sh
+acu --help
+```
+
+## Configuration
+
+Configuration lives in one file plus your SSH setup:
+
+1. **`.env`** — the whole configuration: *where* to apply and *who* signs
+   in, every key an `ACU_*` variable. Three values are required —
+   `ACU_BASE_URL` (the REST root: scheme, host, and site path), `ACU_SSH`
+   (the control-plane `user@host`), and `ACU_PASSWORD`. Everything else
+   has a code default matching a stock Acumatica install:
 
    ```sh
-   acu config show > acu.yaml
+   ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP
+   ACU_SSH=Administrator@acu-dev1.vm.internal
+   ACU_TENANT=Company    # sign-in name of the tenant API sessions use
+   ACU_USER=admin        # optional, defaults to admin
+   ACU_PASSWORD=...      # required
    ```
 
-2. **`.env`** — *who* signs in to the REST API. Loaded from the data-repo
-   root (or the plain environment):
+   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. 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
+   config. The data repo stores the file encrypted as `.env.gpg`;
+   `make decrypt` produces the plaintext `.env` once per clone.
+
+   `acu config show` prints the fully resolved configuration as a
+   complete, valid `.env` — every knob visible, the password excluded.
+   To turn the resolved state into your working config, redirect and
+   edit:
 
    ```sh
-   ACU_PASSWORD=...    # required
-   ACU_USER=admin      # optional, defaults to admin
+   acu config show > .env
    ```
 
-   The data repo stores it encrypted as `.env.gpg`; `make decrypt` produces
-   the plaintext `.env` once per clone.
-
-3. **SSH** — *how* the control plane reaches the Windows guest. Configured on
-   the guest and in your `~/.ssh`, not in `acu.yaml` — see the next section.
+2. **SSH** — *how* the control plane reaches the Windows guest. Configured on
+   the guest and in your `~/.ssh`, not in `.env` — see the next section.
 
 Verify the result before touching anything live:
 
 ```sh
-acu config show           # the fully resolved instance as acu.yaml, no secrets
+acu config check          # read-only preflight: discovery, secrets, REST, SSH
+acu config show           # the fully resolved configuration as .env, no secrets
 acu apply --dry-run baseline/
 ```
 
@@ -110,19 +161,18 @@ acu apply --dry-run baseline/
 
 - **Control plane (SSH):** tenant create/delete/list via `ac.exe
   -cm:CompanyConfig` and `sqlcmd` on the Windows guest — see
-  [`docs/ac-exe.md`](docs/ac-exe.md). Used by `acu tenant` and the first step
-  of `acu provision`.
+  [`docs/ac-exe.md`](docs/ac-exe.md). Used by `acu tenant`.
 - **Data plane (REST):** baseline configuration and reference data through
   the contract-based API (`/entity/Default/25.200.001/`), where `PUT` is a
   keyed upsert — see [`docs/rest-api.md`](docs/rest-api.md). Used by
   `acu apply`, `acu diff`, and `acu schema`.
 
 If you only apply and diff baseline YAML, you never need SSH. SSH setup is
-required only for `acu tenant` and `acu provision`.
+required only for `acu tenant`.
 
 ## SSH setup (control plane)
 
-`acu tenant` and `acu provision` run commands on the Windows guest through
+`acu tenant` runs commands on the Windows guest through
 plain `ssh`. Two things about this setup are not obvious, and both are hard
 requirements:
 
@@ -169,4 +219,4 @@ ssh -o BatchMode=yes Administrator@acu-dev1.vm.internal '$PSVersionTable.PSVersi
 A version table means you are ready; a password prompt or
 `'$PSVersionTable.PSVersion' is not recognized...` means requirement 2 or 1
 (respectively) is not met yet. Host aliases, jump hosts, and ports go in your
-`~/.ssh/config` as usual, or set `ssh: user@alias` in `acu.yaml`.
+`~/.ssh/config` as usual, or set `ACU_SSH=user@alias` in `.env`.

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

@@ -1,7 +1,7 @@
 [project]
 name = "acumatica-cli"
-version = "0.2.2"
-description = "The acu CLI - Acumatica ERP configuration as code: tenant provisioning, baseline config, and reference data"
+version = "0.3.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"
 requires-python = ">=3.12"
@@ -9,11 +9,15 @@ dependencies = [
     "click>=8.1",
     "httpx>=0.27",
     "pydantic>=2.7",
-    "python-dotenv>=1.0",
+    "pydantic-settings>=2.5",
     "pyyaml>=6.0",
     "rich>=13",
 ]
 
+[project.urls]
+Homepage = "https://lab5.ca"
+Repository = "https://github.com/kborovik/acumatica-cli"
+
 [project.scripts]
 acu = "acumatica_cli.cli:main"