Acumatica ERP - GitOps CLI

acu configures Acumatica ERP from YAML files in a git repo (GitOps).

No UI clicks, no Configuration Wizard.

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.

What this tool is capable of

YAML in git is the source of truth; the live tenant is the target. apply is the only writer.

Seed YAML covers features, company, credit terms, subaccounts, chart of accounts, ledger, UOMs, financial year / calendar / periods, numbering sequences, inventory and distribution masters, roles, and users.

REST is the data plane (apply, diff, run, extract, state, bootstrap, schema). SSH is the control plane (tenant *).

Hosted sites skip SSH.

Quick start

uv tool install acumatica-cli

acu config init --host erp.example.com my-erp
cd my-erp                                # edit .env: ACU_PASSWORD, ACU_TENANT
                                         # ACU_BASE_URL is where; ACU_API_VERSION pins Default
                                         # start from a brand-new empty tenant

acu config check                         # read-only preflight
acu tenant create --login DEV            # create + bootstrap (SSH; --id optional)
# or hosted: acu --tenant DEV bootstrap
acu --tenant DEV apply config/           # seed config/{bootstrap,baseline,setup,master}/
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
acu check --yes --tenant DEV             # cold lifecycle create→apply→run→diff (leave tenant)

Bare apply / diff (no path args) also prefer config/ when those trees exist. See docs/demo-seed.md for the entity map, once-guard, apply-order notes, NumberingSequence vs prefs *NumberingID, curated *Preferences field depth (V41), and Role/User + password seed rules.

Hosted Acumatica (no SSH): the tenant already exists; set a blank ACU_SSH= in .env. The scaffold omits the key — without it, acu defaults to Administrator@<ACU_BASE_URL host> for SSH boxes.

acu config init --host customer.acumatica.com my-erp
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/
acu --tenant DEV diff config/
# offline UI fallback when REST publish is blocked:
acu bootstrap --export AcuBootstrap.zip  # import + publish on SM204505

CLI map

acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
    [--username U] [--password P] [--version] [--completion [SHELL]]
│
├── tenant                            tenant CRUD (ac.exe over SSH — control plane)
│   ├── list                          CompanyID, sign-in name, internal CD, type
│   ├── create --login NAME [--id N]  create + bootstrap; re-run to republish (SSH)
│   │          [--type SalesDemo|T100|U100] [--parent N] [--hidden] [--no-init]
│   │                                 omit --id → next free CompanyID (max list + 1)
│   ├── delete --id N | --login NAME [--yes]
│   │                                 delete the tenant and its data, recycle app pool
│   └── recycle [--yes]               restart site app pool (tenant map + free API slots)
│
├── bootstrap [--export PATH]         publish AcuBootstrap (REST); --export = offline zip
├── 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)
├── check [--yes] [--tenant L]        cold lifecycle create→apply→run→diff; leave tenant (V47)
├── state [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
│                                     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
    ├── init [--host HOST] [DIR]      scaffold full data repo (config/, scenario/, .env)
    ├── show                          print the resolved config as a complete .env
    └── check                         preflight: discovery, secrets, REST, endpoints, SSH

When you omit FILES:

• apply / diff prefer config/<name>/ if any seed child exists under config/. Otherwise they walk root bootstrap/, baseline/, setup/, then master/ when present. A path like config/ expands those nested seed dirs in the same order.
• run defaults to scenario/.
• state defaults to config/views/; writes go to state/ (--out).

Scenario YAML may use ${current_period} (host-local MMyyyy) on steps, expect params, and once.present params. config/views and state keep Period pinned — see docs/demo-seed.md.

extract always writes under config/{bootstrap,baseline,setup,master}/ (catalog-driven; never root SEED_DIRS).

inventory and reconcile are offline (no REST, SSH, or password). inventory turns an SM203520 Settings XML ZIP or ac.exe export xml folder into inventory/.

reconcile compares inventory/ to optional config/ and writes findings/ only. It never writes seed.

Optional snapshot_map.yaml (data-repo root, or package defaults) maps DAC tables to catalog entities. It normalizes the join: pad-trim, key/field aliases, Account/Sub FK CD resolve, enum label to code.

See docs/demo-seed.md.

acu --completion emits a completion script for bash, zsh, or fish — source it from your shell profile.

Run acu --help for the full mental model (workflow, planes, exit codes, command map). That is enough for an agent to learn the tool without extra docs.

Run acu <command> --help (or -h) for flags, examples, and prerequisites.

Dual readers, one writer

Two read paths, one mutator (V35). Do not confuse them with each other or with state:

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 for export / SM203520 notes and docs/demo-seed.md for the extract/state/inventory map.

The data repo

Your configuration lives in its own git repo. acu config init scaffolds a single full seed under config/ (features, company, credit terms, expanded COA, masters) plus lifecycle scenario/, observer config/views/, and README.

The Bootstrap endpoint contract is package SoT (bootstrap_project.xml inside the CLI — Bootstrap/1.4.0). config init never writes project.xml, and data repos must not keep one (a present file hard-errors on bootstrap/publish).

There is no --flavor.

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. Commit seed YAML; keep .env out of git (scaffold .gitignore already lists it).

Seed YAML is state: apply upserts it, diff proves it. acu extract is the inverse of apply: GET live tenant rows into seed YAML under config/{bootstrap,baseline,setup,master}/ (hard-cut).

Packaged seed_catalog.yaml is the sole extract registry (entity, endpoint, keys, file, strip/include, filter-split). The demo entity map in docs/demo-seed.md mirrors those catalog paths.

Features synthesize to config/bootstrap/features.yaml. Existing files skip unless --force; empty live sets skip.

Row failures continue (exit 1 only if any row failed). Drift stays with diff.

acu --tenant DEV extract --out . --force   # refresh config/** from live tenant
git diff config/                           # review extract delta before commit
acu --tenant DEV apply config/             # replay extracted seed
acu --tenant DEV diff config/              # expect exit 0

Seed endpoint: symbols

Dual-served entities (on both Bootstrap and Default) need an explicit endpoint: line.

api_version resolves as --api-version flag, else ACU_API_VERSION in .env, else code default 25.200.001. base_url resolves as --url, else ACU_BASE_URL (required).

Prefer symbolic default over a pinned Default/25.200.001 so the seed tree travels with the dataset pin.

Installation

Requires Python 3.14 or newer.

uv tool install acumatica-cli

pipx install acumatica-cli and pip install acumatica-cli work too.

Or clone and install editable for development:

git clone https://github.com/kborovik/acumatica-cli.git
cd acumatica-cli
gmake install    # editable install as a global uv tool

Verify with acu --version.

Configuration

Secrets, REST where, and the Default contract pin live in one .env file (ACU_* vars). Leftover matrix.yaml is ignored and never loaded.

ACU_BASE_URL=http://acu-dev1.vm.internal/AcumaticaERP   # REST where (required)
ACU_API_VERSION=25.200.001                              # Default contract half
ACU_TENANT=LAB5                                         # sign-in name of the tenant API sessions use
# ACU_SSH omitted → defaults to Administrator@ + resolved base_url host
# ACU_SSH=                                              # hosted opt-out (blank key)
ACU_USER=admin                                          # optional, defaults to admin
ACU_PASSWORD=...                                        # required for live commands

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/...).

api_version resolves as --api-version, else ACU_API_VERSION, else 25.200.001. base_url resolves as --url, else ACU_BASE_URL, else a hard error naming sources.

acu config show prints the resolved .env (password excluded; includes ACU_API_VERSION). acu check (lifecycle) uses the same resolved instance.

Multi-host overlays (V44)

One trunk seed in the data repo serves every host. Version fan-out is not long-running product branches (acu-25r1, acu-26r1, …).

Overlays live under overlays/default-<api_version>/ (scaffolded by acu config init). No --overlay flag.

Bare compose (pin auto): when path args are omitted, acu apply / acu diff append overlay config seed dirs when present. acu run replaces same-basename scenario files from the pin overlay.

Pin = resolved api_version (--api-version, else ACU_API_VERSION, else code default). Explicit path args disable auto-compose.

# ACU_API_VERSION=24.200.001 → uses overlays/default-24.200.001/
acu apply
acu run
acu diff

# explicit path args (no auto) — later path wins same keys
acu apply config/ overlays/default-24.200.001/
acu diff config/ overlays/default-24.200.001/

# cold lifecycle vs the resolved .env instance (SSH + tenant required)
acu check --yes --tenant LAB5

Add a future half by creating overlays/default-<new-half>/ with the minimal rewrite; no long-running product branches and no multi-version OpenAPI trees (V11/V44).

Sibling data-repo retirement of release branches: acumatica-gitops#2.

Worth knowing:

• The .env 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 configuration.
• When ACU_SSH is absent, acu defaults to Administrator@ + the resolved base_url hostname. A present blank ACU_SSH= is the hosted opt-out. Only acu tenant / acu check require a non-empty value post-default.
• acu config show prints the resolved .env (password excluded).
• Redirect it to turn resolved state into a working config: acu config show > .env.

Verify before touching anything live:

acu config check           # discovery, secrets, REST, endpoints, SSH
acu apply --dry-run        # show what would be written, write nothing

Development

Requires GNU Make at least 3.82 — the Makefile uses .ONESHELL. On macOS use Homebrew's gmake (brew install make); /usr/bin/make is 3.81 and fails the guard.

Elsewhere plain make is fine when it is GNU Make.

git clone https://github.com/kborovik/acumatica-cli.git
cd acumatica-cli
gmake install    # editable install as a global uv tool
gmake check      # offline gate: ruff, basedpyright strict, pytest

The default test suite is fully offline. REST is faked with httpx.MockTransport, SSH with a monkeypatched subprocess.run — no live instance is needed.

gmake check must pass before every commit. GitHub Actions runs the same gate on every push and pull request to main.

Release

Human release notes live in root CHANGELOG.md (Keep a Changelog). During development, append user-facing work under ## Unreleased in ### Added / ### Changed / ### Fixed as appropriate.

Empty Unreleased (no bullets) hard-fails the release — nothing to ship.

gmake release patch   # or minor | major

gmake release is the sole release path (never local gh release create):

1. gmake check (ruff, basedpyright, offline pytest)
2. Fail if ## Unreleased has no bullets
3. Bump pyproject.toml version (major | minor | patch)
4. Promote Unreleased body to ## [vX.Y.Z] - YYYY-MM-DD, leave an empty ## Unreleased
5. Commit CHANGELOG.md + pyproject.toml (+ lock if bumped) together, tag vX.Y.Z, push

GitHub Actions on tag v* re-runs CI, builds sdist+wheel, publishes to PyPI via OIDC trusted publishing, and creates a GitHub Release whose notes are the promoted CHANGELOG section for that tag (plus the artifacts).

Live end-to-end tier

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_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. Each run scaffolds a synthetic single-org company from the packaged acu config init templates into a temporary directory, copies the real .env into it, and runs the installed acu binary from there — no data repo, no pre-existing fixtures on the instance.

Scratch tenants (E2E, E2EA, E2EB, E2ESCEN) are created on the way in and always deleted on the way out, so nothing persists. The packaged full config init seed (under config/) is the only scaffold.

gmake e2e                                # whole tier, about 20 minutes
gmake e2e FILE=test_provision_lifecycle  # apply/diff focus
gmake e2e FILE=test_scenario_lifecycle   # scenario + state focus

License

This project is licensed under the PolyForm Noncommercial License 1.0.0. Noncommercial use is free under that license.

Commercial use requires a separate license — contact lab5.ca.

See LICENSE and NOTICE.

Copyright 2026 Konstantin Borovik.