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

{akt_cli-0.3.0 → akt_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 # akt — Akaunting CLI toolbox
 ### Drive your Akaunting accounting instance entirely from the command line
 
->`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
+>`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, banks, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
 
 [![PyPI Version](https://img.shields.io/pypi/v/akt-cli.svg?style=flat-square)](https://pypi.org/project/akt-cli/)
 [![Tests](https://img.shields.io/github/actions/workflow/status/AsyncAlchemist/akt-cli/ci.yml?branch=main&label=tests&style=flat-square)](https://github.com/AsyncAlchemist/akt-cli/actions/workflows/ci.yml)
@@ -102,13 +102,14 @@ Akaunting folds several nouns onto shared endpoints; `akt` hides that:
 | `bill`     | `documents`    | document of type `bill`                            |
 | `payment`  | `transactions` | income (invoice) or expense (bill) transaction    |
 | `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
-| `chart-of-account` | `chart-of-accounts` | GL accounts — read via API, CRUD via web    |
-| `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
+| `account`  | `chart-of-accounts` | GL accounts (general ledger) — read via API, CRUD via web |
+| `bank`     | `accounts`     | bank / cash accounts (the money, not the GL)      |
+| `item`, `category`, `tax`, `currency`, `transfer` | as named | |
 
-> `journal-entry` and `chart-of-account` require the **Double-Entry** module
+> `journal-entry` and `account` require the **Double-Entry** module
 > installed on the instance. The module publishes chart-of-accounts read-only on
 > the `/api` surface (index/show); its create/update/delete live only on the
-> session/CSRF **web** route. `akt chart-of-account` gives you the full verb set
+> session/CSRF **web** route. `akt account` gives you the full verb set
 > anyway — `list`/`get` hit `/api`, while `create`/`update`/`delete` transparently
 > drive the web CRUD with your admin session (the same mechanism
 > `download-attachment` already uses).
@@ -166,6 +167,10 @@ akt item create --name "Consulting Hour" --sale-price 150 --purchase-price 0
 akt category create --name "Services" --type income
 akt tax create --name "Sales Tax" --rate 8.25
 
+# Bank / cash accounts (the money side — see the COA section below for GL accounts)
+akt bank create --name "Business Checking" --number 1001 --currency-code USD
+akt bank list
+
 # Invoice with line items (totals computed server-side; number auto-generated)
 akt invoice create --contact 12 \
     --item 'name=Consulting,price=150,quantity=10,item_id=2' \
@@ -192,16 +197,16 @@ akt bill download-attachment 41 --out ./downloads   # save to disk
 akt payment update 57 --remove-attachment           # clear attachments
 
 # Double-entry general ledger (requires the Double-Entry module)
-akt chart-of-account list                              # read the chart of accounts
-akt chart-of-account get 12
+akt account list                                       # read the chart of accounts
+akt account get 12
 
 # Build the chart of accounts as code (create/update/delete run via the web
 # session; type-id is the double-entry account-type id — copy it from an
 # existing account's `type_id`)
-akt chart-of-account create --name "Cash on Hand" --code 1010 --type-id 6
-akt chart-of-account create --name "Petty Cash" --code 1011 --type-id 6 --account-id 12
-akt chart-of-account update 12 --code 1000 --description "Operating cash"
-akt chart-of-account delete 12
+akt account create --name "Cash on Hand" --code 1010 --type-id 6
+akt account create --name "Petty Cash" --code 1011 --type-id 6 --parent-id 12
+akt account update 12 --code 1000 --description "Operating cash"
+akt account delete 12
 
 # Post a balanced journal entry (>= 2 lines; debits must equal credits;
 # journal number auto-generated, basis defaults to accrual)
@@ -214,6 +219,38 @@ akt journal-entry create --description "Vendor bill accrual" --basis accrual \
     --item 'account_id=60,debit=250' --item 'account_id=21,credit=250' \
     --attachment ./invoice.pdf
 
+## COA config: link categories and accounts (Xero-style)
+
+Akaunting keeps *categories* (required on every transaction) separate from the
+double-entry *chart of accounts*. Point akt at a COA config and it keeps them in
+lockstep: one list to maintain (accounts), a 1:1 mirror of categories generated
+from it, and `payment create` coded by `--account` — with the mirror category
+filled in automatically.
+
+akt finds the config at `--coa FILE` → `AKT_COA_FILE` → `./coa.toml` →
+`~/.config/akt/coa.toml`. Minimal schema (extra keys are ignored):
+
+```toml
+[[account]]
+code    = 400
+name    = "API Subscription Revenue"
+type_id = 13            # DoubleEntry account type; income/expense class -> category type
+# optional: category = "Revenue"   (override the mirror name)
+# optional: mirror   = false        (skip mirroring, e.g. bank/AR/AP accounts)
+```
+
+```bash
+akt coa diff                 # preview: accounts/categories to create or rename
+akt coa sync                 # apply (create + rename; idempotent)
+akt coa sync --prune         # also DISABLE accounts/categories absent from the config
+
+# code a transaction by GL account — akt auto-fills the mirror category:
+akt payment create --type expense --bank 1 --amount 120 --account 628
+```
+
+`--account` takes a GL code or name (the double-entry account; see `--bank` for
+the bank/cash account). An explicit `--set de_account_id=` still wins.
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -260,7 +297,7 @@ Driving Akaunting's API directly has sharp edges; `akt` papers over these:
   `double-entry.journal.number_*` settings when you don't pass one.
 * **Chart-of-accounts CRUD is web-only** — the Double-Entry module exposes
   accounts read-only on `/api`; create/update/delete exist solely on the
-  session/CSRF web route. `akt chart-of-account create|update|delete` logs in a
+  session/CSRF web route. `akt account create|update|delete` logs in a
   web session (reusing your admin credentials, cached for the process), attaches
   the CSRF token, and unwraps Akaunting's `{success, error, data, message}` AJAX
   envelope — so a server-side block (e.g. *deleting an account that has ledgers*)
@@ -286,75 +323,10 @@ timing out. `akt` retries throttle/WAF responses with backoff, and
 use `--throttle 1` for bulk work. A durable fix is to whitelist your IP in the
 host firewall.
 
-## Testing
-
-Tests are split in two:
-
-* **`tests/unit/`** — offline tests for the body builders and arg parsing. No
-  network. This is what CI runs by default and what gates pull requests.
-* **`tests/integration/`** — drive the real `akt` CLI against a live Akaunting
-  instance, exercising the full surface (contacts, items, bill → payment →
-  paid, transfers, …). Every record they create is deleted on teardown — even
-  on failure — so no invoices, bills or payments are left behind.
-
-```bash
-uv run pytest tests/unit                 # fast, offline (default)
-uv run pytest                            # integration tests auto-skip without creds
-
-# Run integration tests against a deployment:
-AKT_BASE_URL=https://accounting.example.com \
-AKT_EMAIL=admin@example.com \
-AKT_PASSWORD=… \
-uv run pytest tests/integration -v
-```
-
-> Invoice creation is `xfail`-ed when the host's plan-limit gate is active (see
-> above); the rest of the suite must pass.
-
-### CI / CD
-
-* **CI** (`.github/workflows/ci.yml`) runs on every push and PR: unit tests +
-  coverage, uploaded to [Codecov](https://codecov.io/gh/AsyncAlchemist/akt-cli).
-* **Release** (`.github/workflows/release.yml`) runs the live integration suite
-  on published releases (and via *Run workflow*). Connection details come from
-  GitHub Actions **secrets** (`AKT_BASE_URL`, `AKT_EMAIL`, `AKT_PASSWORD`) — they
-  are never committed and are masked in logs.
-* **Publish** (`.github/workflows/publish.yml`) builds the sdist + wheel and
-  uploads them via **Trusted Publishing (OIDC)** — no API token is stored.
-  *Run workflow* publishes to **TestPyPI**; a published release publishes to
-  **PyPI**.
-
-### Releasing to PyPI
-
-One-time setup — add a *pending publisher* on each index
-(Account → Publishing → *Add a pending publisher*) with:
-
-| Field | TestPyPI | PyPI |
-|-------|----------|------|
-| Project Name | `akt-cli` | `akt-cli` |
-| Owner | `AsyncAlchemist` | `AsyncAlchemist` |
-| Repository name | `akt-cli` | `akt-cli` |
-| Workflow name | `publish.yml` | `publish.yml` |
-| Environment name | `testpypi` | `pypi` |
-
-Then:
+## Contributing
 
-* **Verify** — *Actions → Publish (PyPI) → Run workflow* uploads the current
-  version to TestPyPI.
-* **Release** — bump `version` in `pyproject.toml`, push, and publish a GitHub
-  Release. That runs the live integration suite and publishes to PyPI.
-
-The code is small and declarative:
-
-| file            | purpose                                                  |
-|-----------------|----------------------------------------------------------|
-| `config.py`     | credential resolution (flags / env / dotenv)             |
-| `client.py`     | HTTP, auth, company scoping, pagination, retries         |
-| `resources.py`  | field specs + body builders (documents, payments)        |
-| `registry.py`   | the concrete list of resources and their columns         |
-| `commands.py`   | generic list/get/create/update/delete/toggle handlers    |
-| `cli.py`        | argparse wiring and entrypoint                            |
-| `output.py`     | JSON / table rendering                                    |
+Developing, testing, or releasing `akt`? See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the test suite, CI/CD, release process, and a map of the source files.
 
 ## License
 

{akt_cli-0.3.0 → akt_cli-0.4.0}/README.md

@@ -3,7 +3,7 @@
 # akt — Akaunting CLI toolbox
 ### Drive your Akaunting accounting instance entirely from the command line
 
->`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
+>`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, banks, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
 
 [![PyPI Version](https://img.shields.io/pypi/v/akt-cli.svg?style=flat-square)](https://pypi.org/project/akt-cli/)
 [![Tests](https://img.shields.io/github/actions/workflow/status/AsyncAlchemist/akt-cli/ci.yml?branch=main&label=tests&style=flat-square)](https://github.com/AsyncAlchemist/akt-cli/actions/workflows/ci.yml)
@@ -81,13 +81,14 @@ Akaunting folds several nouns onto shared endpoints; `akt` hides that:
 | `bill`     | `documents`    | document of type `bill`                            |
 | `payment`  | `transactions` | income (invoice) or expense (bill) transaction    |
 | `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
-| `chart-of-account` | `chart-of-accounts` | GL accounts — read via API, CRUD via web    |
-| `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
+| `account`  | `chart-of-accounts` | GL accounts (general ledger) — read via API, CRUD via web |
+| `bank`     | `accounts`     | bank / cash accounts (the money, not the GL)      |
+| `item`, `category`, `tax`, `currency`, `transfer` | as named | |
 
-> `journal-entry` and `chart-of-account` require the **Double-Entry** module
+> `journal-entry` and `account` require the **Double-Entry** module
 > installed on the instance. The module publishes chart-of-accounts read-only on
 > the `/api` surface (index/show); its create/update/delete live only on the
-> session/CSRF **web** route. `akt chart-of-account` gives you the full verb set
+> session/CSRF **web** route. `akt account` gives you the full verb set
 > anyway — `list`/`get` hit `/api`, while `create`/`update`/`delete` transparently
 > drive the web CRUD with your admin session (the same mechanism
 > `download-attachment` already uses).
@@ -145,6 +146,10 @@ akt item create --name "Consulting Hour" --sale-price 150 --purchase-price 0
 akt category create --name "Services" --type income
 akt tax create --name "Sales Tax" --rate 8.25
 
+# Bank / cash accounts (the money side — see the COA section below for GL accounts)
+akt bank create --name "Business Checking" --number 1001 --currency-code USD
+akt bank list
+
 # Invoice with line items (totals computed server-side; number auto-generated)
 akt invoice create --contact 12 \
     --item 'name=Consulting,price=150,quantity=10,item_id=2' \
@@ -171,16 +176,16 @@ akt bill download-attachment 41 --out ./downloads   # save to disk
 akt payment update 57 --remove-attachment           # clear attachments
 
 # Double-entry general ledger (requires the Double-Entry module)
-akt chart-of-account list                              # read the chart of accounts
-akt chart-of-account get 12
+akt account list                                       # read the chart of accounts
+akt account get 12
 
 # Build the chart of accounts as code (create/update/delete run via the web
 # session; type-id is the double-entry account-type id — copy it from an
 # existing account's `type_id`)
-akt chart-of-account create --name "Cash on Hand" --code 1010 --type-id 6
-akt chart-of-account create --name "Petty Cash" --code 1011 --type-id 6 --account-id 12
-akt chart-of-account update 12 --code 1000 --description "Operating cash"
-akt chart-of-account delete 12
+akt account create --name "Cash on Hand" --code 1010 --type-id 6
+akt account create --name "Petty Cash" --code 1011 --type-id 6 --parent-id 12
+akt account update 12 --code 1000 --description "Operating cash"
+akt account delete 12
 
 # Post a balanced journal entry (>= 2 lines; debits must equal credits;
 # journal number auto-generated, basis defaults to accrual)
@@ -193,6 +198,38 @@ akt journal-entry create --description "Vendor bill accrual" --basis accrual \
     --item 'account_id=60,debit=250' --item 'account_id=21,credit=250' \
     --attachment ./invoice.pdf
 
+## COA config: link categories and accounts (Xero-style)
+
+Akaunting keeps *categories* (required on every transaction) separate from the
+double-entry *chart of accounts*. Point akt at a COA config and it keeps them in
+lockstep: one list to maintain (accounts), a 1:1 mirror of categories generated
+from it, and `payment create` coded by `--account` — with the mirror category
+filled in automatically.
+
+akt finds the config at `--coa FILE` → `AKT_COA_FILE` → `./coa.toml` →
+`~/.config/akt/coa.toml`. Minimal schema (extra keys are ignored):
+
+```toml
+[[account]]
+code    = 400
+name    = "API Subscription Revenue"
+type_id = 13            # DoubleEntry account type; income/expense class -> category type
+# optional: category = "Revenue"   (override the mirror name)
+# optional: mirror   = false        (skip mirroring, e.g. bank/AR/AP accounts)
+```
+
+```bash
+akt coa diff                 # preview: accounts/categories to create or rename
+akt coa sync                 # apply (create + rename; idempotent)
+akt coa sync --prune         # also DISABLE accounts/categories absent from the config
+
+# code a transaction by GL account — akt auto-fills the mirror category:
+akt payment create --type expense --bank 1 --amount 120 --account 628
+```
+
+`--account` takes a GL code or name (the double-entry account; see `--bank` for
+the bank/cash account). An explicit `--set de_account_id=` still wins.
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -239,7 +276,7 @@ Driving Akaunting's API directly has sharp edges; `akt` papers over these:
   `double-entry.journal.number_*` settings when you don't pass one.
 * **Chart-of-accounts CRUD is web-only** — the Double-Entry module exposes
   accounts read-only on `/api`; create/update/delete exist solely on the
-  session/CSRF web route. `akt chart-of-account create|update|delete` logs in a
+  session/CSRF web route. `akt account create|update|delete` logs in a
   web session (reusing your admin credentials, cached for the process), attaches
   the CSRF token, and unwraps Akaunting's `{success, error, data, message}` AJAX
   envelope — so a server-side block (e.g. *deleting an account that has ledgers*)
@@ -265,75 +302,10 @@ timing out. `akt` retries throttle/WAF responses with backoff, and
 use `--throttle 1` for bulk work. A durable fix is to whitelist your IP in the
 host firewall.
 
-## Testing
-
-Tests are split in two:
-
-* **`tests/unit/`** — offline tests for the body builders and arg parsing. No
-  network. This is what CI runs by default and what gates pull requests.
-* **`tests/integration/`** — drive the real `akt` CLI against a live Akaunting
-  instance, exercising the full surface (contacts, items, bill → payment →
-  paid, transfers, …). Every record they create is deleted on teardown — even
-  on failure — so no invoices, bills or payments are left behind.
-
-```bash
-uv run pytest tests/unit                 # fast, offline (default)
-uv run pytest                            # integration tests auto-skip without creds
-
-# Run integration tests against a deployment:
-AKT_BASE_URL=https://accounting.example.com \
-AKT_EMAIL=admin@example.com \
-AKT_PASSWORD=… \
-uv run pytest tests/integration -v
-```
-
-> Invoice creation is `xfail`-ed when the host's plan-limit gate is active (see
-> above); the rest of the suite must pass.
-
-### CI / CD
-
-* **CI** (`.github/workflows/ci.yml`) runs on every push and PR: unit tests +
-  coverage, uploaded to [Codecov](https://codecov.io/gh/AsyncAlchemist/akt-cli).
-* **Release** (`.github/workflows/release.yml`) runs the live integration suite
-  on published releases (and via *Run workflow*). Connection details come from
-  GitHub Actions **secrets** (`AKT_BASE_URL`, `AKT_EMAIL`, `AKT_PASSWORD`) — they
-  are never committed and are masked in logs.
-* **Publish** (`.github/workflows/publish.yml`) builds the sdist + wheel and
-  uploads them via **Trusted Publishing (OIDC)** — no API token is stored.
-  *Run workflow* publishes to **TestPyPI**; a published release publishes to
-  **PyPI**.
-
-### Releasing to PyPI
-
-One-time setup — add a *pending publisher* on each index
-(Account → Publishing → *Add a pending publisher*) with:
-
-| Field | TestPyPI | PyPI |
-|-------|----------|------|
-| Project Name | `akt-cli` | `akt-cli` |
-| Owner | `AsyncAlchemist` | `AsyncAlchemist` |
-| Repository name | `akt-cli` | `akt-cli` |
-| Workflow name | `publish.yml` | `publish.yml` |
-| Environment name | `testpypi` | `pypi` |
-
-Then:
+## Contributing
 
-* **Verify** — *Actions → Publish (PyPI) → Run workflow* uploads the current
-  version to TestPyPI.
-* **Release** — bump `version` in `pyproject.toml`, push, and publish a GitHub
-  Release. That runs the live integration suite and publishes to PyPI.
-
-The code is small and declarative:
-
-| file            | purpose                                                  |
-|-----------------|----------------------------------------------------------|
-| `config.py`     | credential resolution (flags / env / dotenv)             |
-| `client.py`     | HTTP, auth, company scoping, pagination, retries         |
-| `resources.py`  | field specs + body builders (documents, payments)        |
-| `registry.py`   | the concrete list of resources and their columns         |
-| `commands.py`   | generic list/get/create/update/delete/toggle handlers    |
-| `cli.py`        | argparse wiring and entrypoint                            |
-| `output.py`     | JSON / table rendering                                    |
+Developing, testing, or releasing `akt`? See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the test suite, CI/CD, release process, and a map of the source files.
 
 ## License
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "akt-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "akt — a CLI toolbox to fully drive an Akaunting accounting instance"
 readme = "README.md"
 license = "MIT"

{akt_cli-0.3.0 → akt_cli-0.4.0}/src/akt/cli.py

@@ -21,6 +21,7 @@ from .commands import (
 from .output import emit
 from .registry import RESOURCES, BY_NOUN
 from .resources import Resource, load_data_arg
+from .coa import load_coa, plan_sync, render_plan, apply_plan
 
 
 def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
@@ -84,6 +85,9 @@ def _build_parser() -> argparse.ArgumentParser:
                         metavar="SECONDS",
                         help="Min seconds between API calls (or AKT_THROTTLE). "
                              "Use a value like 1.0 to avoid tripping host bot-protection.")
+    parser.add_argument("--coa", dest="coa_file", default=None, metavar="FILE",
+                        help="COA config for category<->account linking "
+                             "(or AKT_COA_FILE / ./coa.toml / ~/.config/akt/coa.toml)")
 
     sub = parser.add_subparsers(dest="resource", metavar="<resource>")
 
@@ -159,6 +163,19 @@ def _build_parser() -> argparse.ArgumentParser:
     rp.add_argument("--type-scope", help="search=type:X scope for contacts/documents")
     rp.set_defaults(_special="raw")
 
+    coap = sub.add_parser("coa", parents=[common],
+                          help="Sync chart-of-accounts <-> categories from a COA config")
+    coav = coap.add_subparsers(dest="coa_verb", metavar="<verb>")
+    cdp = coav.add_parser("diff", parents=[common], help="Preview the sync plan (read-only)")
+    cdp.add_argument("--prune", action="store_true",
+                     help="also show accounts/categories that --prune would disable")
+    cdp.set_defaults(_special="coa_diff")
+    csp = coav.add_parser("sync", parents=[common],
+                          help="Apply: create/rename accounts + mirror categories")
+    csp.add_argument("--prune", action="store_true",
+                     help="disable accounts/categories absent from the config (never deletes)")
+    csp.set_defaults(_special="coa_sync")
+
     return parser
 
 
@@ -185,6 +202,30 @@ def _run_special(name: str, client: Client, ns: Any) -> int:
                                 json_body=body, type_scope=ns.type_scope)
         emit(result, as_json=True)
         return 0
+    if name == "coa_diff":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("no COA config found (use --coa FILE or set AKT_COA_FILE)")
+        live_accounts = client.list("chart-of-accounts", all_pages=True)
+        live_categories = client.list("categories", all_pages=True)
+        plan = plan_sync(coa, live_accounts, live_categories, prune=ns.prune)
+        for line in render_plan(plan):
+            print(line)
+        return 0
+    if name == "coa_sync":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("no COA config found (use --coa FILE or set AKT_COA_FILE)")
+        live_accounts = client.list("chart-of-accounts", all_pages=True)
+        live_categories = client.list("categories", all_pages=True)
+        plan = plan_sync(coa, live_accounts, live_categories, prune=ns.prune)
+        for line in render_plan(plan):
+            print(line)
+        if plan.is_empty:
+            return 0
+        summary = apply_plan(client, plan, prune=ns.prune)
+        print("applied: " + ", ".join(f"{k}={v}" for k, v in summary.items() if v))
+        return 0
     raise ValueError(name)
 
 
@@ -216,11 +257,24 @@ def main(argv: list[str] | None = None) -> int:
         throttle = float(os.environ.get("AKT_THROTTLE", "0") or 0)
     client = Client(config, throttle=throttle)
 
+    try:
+        ns._coa = load_coa(getattr(ns, "coa_file", None))
+    except (ValueError, OSError) as e:
+        print(f"coa config error: {e}", file=sys.stderr)
+        return 2
+
     try:
         special = getattr(ns, "_special", None)
         if special:
             return _run_special(special, client, ns)
 
+        if ns.resource not in BY_NOUN:
+            # command group (e.g. "coa") invoked without a verb
+            sub = next(a for a in parser._subparsers._actions  # type: ignore[attr-defined]
+                       if a.dest == "resource")
+            sub.choices[ns.resource].print_help()  # type: ignore[union-attr]
+            return 1
+
         res = BY_NOUN[ns.resource]
         handler = getattr(ns, "_handler", None)
         if handler is None:

akt_cli-0.4.0/src/akt/coa.py

@@ -0,0 +1,289 @@
+"""Config-driven chart-of-accounts <-> category linking.
+
+akt defines a small COA config schema. When present, it lets `coa sync`
+reconcile the double-entry chart of accounts and a 1:1 mirror of Akaunting
+categories, and lets `payment create` code by --account with the mirror
+category filled in automatically. The feature is inert when no config is found.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# DoubleEntry standard seeds: account type_id -> Akaunting category type.
+# Income classes -> "income", Expense classes -> "expense", everything else
+# (assets/liabilities/equity) -> "other".
+TYPE_ID_CATEGORY_TYPE: dict[int, str] = {
+    13: "income", 14: "income", 15: "income",          # revenue, sales, other_income
+    11: "expense", 12: "expense",                       # direct_costs, expense
+    1: "other", 2: "other", 3: "other", 4: "other",     # asset types
+    5: "other", 6: "other", 10: "other",                # prepayment, bank_cash, depreciation
+    7: "other", 8: "other", 9: "other", 17: "other",    # liability types + tax
+    16: "other",                                        # equity
+}
+
+
+@dataclass(frozen=True)
+class CoaAccount:
+    code: int
+    name: str
+    type_id: int
+    category: str        # mirror category name (== name unless overridden)
+    category_type: str   # "income" | "expense" | "other"
+    mirror: bool         # whether to create/keep a mirror category
+
+
+@dataclass
+class CoaConfig:
+    accounts: list[CoaAccount] = field(default_factory=list)
+
+    def by_code(self, code: int) -> CoaAccount | None:
+        for a in self.accounts:
+            if a.code == int(code):
+                return a
+        return None
+
+    def by_name(self, name: str) -> CoaAccount | None:
+        for a in self.accounts:
+            if a.name == name:
+                return a
+        return None
+
+    @property
+    def mirrored(self) -> list[CoaAccount]:
+        return [a for a in self.accounts if a.mirror]
+
+
+def parse_coa(text: str) -> CoaConfig:
+    doc = tomllib.loads(text)
+    raw_accounts = doc.get("account", [])
+    accounts: list[CoaAccount] = []
+    seen_codes: set[int] = set()
+    seen_categories: set[str] = set()
+    for i, row in enumerate(raw_accounts):
+        if "code" not in row:
+            raise ValueError(f"account #{i + 1}: missing required 'code'")
+        if "name" not in row:
+            raise ValueError(f"account #{i + 1} (code {row['code']}): missing required 'name'")
+        if "type_id" not in row:
+            raise ValueError(f"account '{row['name']}': missing required 'type_id'")
+        code = int(row["code"])
+        name = str(row["name"])
+        type_id = int(row["type_id"])
+        mirror = bool(row.get("mirror", True))
+        category = str(row.get("category", name))
+        if code in seen_codes:
+            raise ValueError(f"duplicate code {code}")
+        seen_codes.add(code)
+        if type_id not in TYPE_ID_CATEGORY_TYPE:
+            print(f"warning: unknown type_id {type_id} for account '{name}'; "
+                  f"mirror category type defaulted to 'other'", file=sys.stderr)
+        category_type = TYPE_ID_CATEGORY_TYPE.get(type_id, "other")
+        if mirror:
+            if category in seen_categories:
+                raise ValueError(f"duplicate category name {category!r} "
+                                 f"(mirror category names must be unique)")
+            seen_categories.add(category)
+        accounts.append(CoaAccount(code=code, name=name, type_id=type_id,
+                                   category=category, category_type=category_type,
+                                   mirror=mirror))
+    return CoaConfig(accounts=accounts)
+
+
+def _coa_candidate_files(explicit: str | None) -> list[Path]:
+    if explicit:
+        return [Path(explicit).expanduser()]
+    files: list[Path] = []
+    if os.environ.get("AKT_COA_FILE"):
+        files.append(Path(os.environ["AKT_COA_FILE"]).expanduser())
+    files.append(Path.cwd() / "coa.toml")
+    files.append(Path.home() / ".config" / "akt" / "coa.toml")
+    return files
+
+
+def load_coa(path: str | None = None) -> CoaConfig | None:
+    """Find and parse the COA config; return None if none is present.
+
+    An explicitly-passed ``path`` that does not exist is an error (the user
+    asked for a specific file); discovered defaults simply fall through."""
+    if path and not Path(path).expanduser().is_file():
+        raise ValueError(f"COA config not found: {path}")
+    for f in _coa_candidate_files(path):
+        if f.is_file():
+            return parse_coa(f.read_text())
+    return None
+
+
+@dataclass
+class CoaPlan:
+    accounts_create: list[CoaAccount] = field(default_factory=list)
+    accounts_rename: list[tuple[CoaAccount, dict]] = field(default_factory=list)
+    categories_create: list[CoaAccount] = field(default_factory=list)
+    categories_rename: list[tuple[CoaAccount, dict]] = field(default_factory=list)
+    accounts_disable: list[dict] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not any([self.accounts_create, self.accounts_rename,
+                        self.categories_create, self.categories_rename,
+                        self.accounts_disable])
+
+
+def plan_sync(config: CoaConfig, live_accounts: list[dict],
+              live_categories: list[dict], *, prune: bool) -> CoaPlan:
+    """Diff the config against live Akaunting data. Pure: no I/O."""
+    plan = CoaPlan()
+    live_by_code = {int(a["code"]): a for a in live_accounts if a.get("code") is not None}
+    # (name, type) -> live category, so a same-named category of another type
+    # never gets clobbered.
+    live_cat = {(c.get("name"), c.get("type")): c for c in live_categories}
+
+    for acct in config.accounts:
+        live = live_by_code.get(acct.code)
+        if live is None:
+            plan.accounts_create.append(acct)
+        elif str(live.get("name")) != acct.name:
+            plan.accounts_rename.append((acct, live))
+
+    # A renamed mirrored account's mirror category currently lives under the account's
+    # OLD name; rename it instead of creating a fresh one (which would orphan the old).
+    rename_targets = {}   # (new category, type) -> (acct, live_old_category)
+    for acct, live in plan.accounts_rename:
+        if not acct.mirror:
+            continue
+        old = live_cat.get((str(live.get("name")), acct.category_type))
+        if old is not None and old.get("name") != acct.category:
+            rename_targets[(acct.category, acct.category_type)] = (acct, old)
+
+    # Mirror-category names are unique by construction (parse_coa rejects
+    # duplicate category names among mirrored accounts), so these loops can
+    # never enqueue the same categories_create/categories_rename entry twice.
+    for acct in config.mirrored:
+        key = (acct.category, acct.category_type)
+        if live_cat.get(key) is not None:
+            continue                      # already correct
+        if key in rename_targets:
+            a, old = rename_targets[key]
+            plan.categories_rename.append((a, old))   # rename old -> a.category
+        else:
+            plan.categories_create.append(acct)
+
+    if prune:
+        config_codes = {a.code for a in config.accounts}
+        for live in live_accounts:
+            code = live.get("code")
+            if code is None:
+                continue
+            if int(code) not in config_codes and int(live.get("enabled", 1)) == 1:
+                plan.accounts_disable.append(live)
+    return plan
+
+
+def render_plan(plan: CoaPlan) -> list[str]:
+    lines: list[str] = []
+    for a in plan.accounts_create:
+        lines.append(f"create account {a.code} {a.name} (type_id {a.type_id})")
+    for a, live in plan.accounts_rename:
+        lines.append(f"rename account {a.code}: {live.get('name')!r} -> {a.name!r}")
+    for a in plan.categories_create:
+        lines.append(f"create category {a.category!r} [{a.category_type}]")
+    for a, live in plan.categories_rename:
+        lines.append(f"rename category {live.get('name')!r} -> {a.category!r}")
+    for live in plan.accounts_disable:
+        lines.append(f"disable account {live.get('code')} {live.get('name')!r}")
+    if not lines:
+        lines.append("in sync — nothing to do")
+    return lines
+
+
+def _account_form(acct: CoaAccount) -> list[tuple[str, str]]:
+    """The web-CRUD form body for a chart-of-accounts create/update."""
+    from .resources import flatten_form  # local import: avoids resources<->coa cycle
+    return flatten_form({
+        "code": acct.code,
+        "name": acct.name,
+        "type_id": acct.type_id,
+        "enabled": 1,
+        "is_sub_account": "false",
+    })
+
+
+def apply_plan(client, plan: "CoaPlan", *, prune: bool) -> dict:
+    """Execute the plan against Akaunting. Accounts use the web CRUD route
+    (chart-of-accounts is read-only on /api); categories use /api."""
+    summary = {"accounts_created": 0, "accounts_renamed": 0,
+               "categories_created": 0, "categories_renamed": 0,
+               "accounts_disabled": 0}
+
+    for acct in plan.accounts_create:
+        client.web_json("POST", "double-entry/chart-of-accounts", _account_form(acct))
+        summary["accounts_created"] += 1
+
+    for acct, live in plan.accounts_rename:
+        client.web_json("PATCH", f"double-entry/chart-of-accounts/{live['id']}",
+                        _account_form(acct))
+        summary["accounts_renamed"] += 1
+
+    for acct in plan.categories_create:
+        client.post("categories", {
+            "name": acct.category,
+            "type": acct.category_type,
+            "color": "#00bcd4",
+            "enabled": 1,
+        })
+        summary["categories_created"] += 1
+
+    for acct, live in plan.categories_rename:
+        client.put(f"categories/{live['id']}", {
+            "name": acct.category,
+            "type": acct.category_type,
+            "color": live.get("color") or "#00bcd4",
+            "enabled": 1,
+        })
+        summary["categories_renamed"] += 1
+
+    if prune:
+        for live in plan.accounts_disable:
+            client.web_json("GET", f"double-entry/chart-of-accounts/{live['id']}/disable")
+            summary["accounts_disabled"] += 1
+
+    return summary
+
+
+def _find_account(config: CoaConfig, ref: str) -> CoaAccount:
+    acct = config.by_code(int(ref)) if str(ref).lstrip("-").isdigit() else config.by_name(ref)
+    if acct is None:
+        raise ValueError(f"account {ref!r} is not in the COA config")
+    return acct
+
+
+def resolve_coding(config: CoaConfig, client, *, account_ref: str) -> tuple[int, int]:
+    """Resolve --account to live (de_account_id, category_id).
+
+    The account must already exist in Akaunting (run `coa sync`); category_id
+    is auto-derived from its mirror category, which must also already exist."""
+    acct = _find_account(config, account_ref)
+
+    if not acct.mirror:
+        raise ValueError(
+            f"account {acct.code} ({acct.name}) has mirror=false — it has no mirror "
+            f"category, so it can't be coded onto a payment via --account "
+            f"(only mirrored income/expense accounts can be)")
+
+    live_accounts = client.list("chart-of-accounts", all_pages=True)
+    de_id = next((a["id"] for a in live_accounts if int(a.get("code", -1)) == acct.code), None)
+    if de_id is None:
+        raise ValueError(f"account {acct.code} ({acct.name}) is not in Akaunting yet — "
+                         f"run `akt coa sync` first")
+    live_categories = client.list("categories", all_pages=True)
+    cat_id = next((c["id"] for c in live_categories
+                   if c.get("name") == acct.category and c.get("type") == acct.category_type),
+                  None)
+    if cat_id is None:
+        raise ValueError(f"mirror category {acct.category!r} [{acct.category_type}] is not in "
+                         f"Akaunting yet — run `akt coa sync` first")
+    return int(de_id), int(cat_id)

{akt_cli-0.3.0 → akt_cli-0.4.0}/src/akt/registry.py

@@ -92,8 +92,8 @@ ITEM = Resource(
     help="Products and services",
 )
 
-ACCOUNT = Resource(
-    noun="account",
+BANK = Resource(
+    noun="bank",
     endpoint="accounts",
     fields=[
         f("name", "Account name", required=True),
@@ -220,10 +220,13 @@ PAYMENT = Resource(
         f("type", "income | expense", choices=["income", "expense"]),
         f("invoice", "Invoice id to apply an income payment to"),
         f("bill", "Bill id to apply an expense payment to"),
+        f("account", "GL/chart-of-accounts code or name to post to (the double-entry "
+                     "account). Requires a --coa config; auto-fills the mirrored "
+                     "category. See --bank for the bank/cash account."),
         f("document-id", "Linked document id (advanced)"),
         f("contact-id", "Contact id"),
         f("amount", "Payment amount"),
-        f("account-id", "Bank/cash account id"),
+        f("bank", "Bank/cash account id", dest="account_id"),
         f("category-id", "Category id"),
         f("paid-at", "Payment date/time (YYYY-MM-DD)"),
         f("currency-code", "Currency code"),
@@ -246,8 +249,8 @@ TRANSFER = Resource(
     noun="transfer",
     endpoint="transfers",
     fields=[
-        f("from-account-id", "Source account id", required=True),
-        f("to-account-id", "Destination account id", required=True),
+        f("from-bank", "Source bank/cash account id", dest="from_account_id", required=True),
+        f("to-bank", "Destination bank/cash account id", dest="to_account_id", required=True),
         f("amount", "Amount", required=True),
         f("transferred-at", "Transfer date/time (YYYY-MM-DD)"),
         f("payment-method", "Payment method code", default="offline-payments.cash.1"),
@@ -272,15 +275,15 @@ TRANSFER = Resource(
 # while list/get keep using the /api surface (endpoint). journal-entry is full
 # API CRUD.
 
-CHART_OF_ACCOUNT = Resource(
-    noun="chart-of-account",
+ACCOUNT = Resource(
+    noun="account",
     endpoint="chart-of-accounts",
     web_endpoint="double-entry/chart-of-accounts",
     fields=[
         f("name", "Account name", required=True),
         f("code", "Account code (unique integer per company)"),
         f("type-id", "Double-entry account type id (see an existing account's type_id)"),
-        f("account-id", "Parent account id (makes this a sub-account)"),
+        f("parent-id", "Parent account id (makes this a sub-account)", dest="account_id"),
         f("description", "Description"),
         f("enabled", "Enable the record", is_flag=True, default=1),
     ],
@@ -291,7 +294,8 @@ CHART_OF_ACCOUNT = Resource(
     supports_toggle=False,
     build_create=build_account_create,
     build_update=build_account_update,
-    help="Chart of accounts (read via API; create/update/delete via web, double-entry module)",
+    help="Chart of accounts (general ledger; read via API, create/update/delete via web, "
+         "double-entry module)",
 )
 
 JOURNAL_ENTRY = Resource(
@@ -320,9 +324,9 @@ JOURNAL_ENTRY = Resource(
 
 
 RESOURCES: list[Resource] = [
-    CUSTOMER, VENDOR, ITEM, ACCOUNT, CATEGORY, TAX, CURRENCY,
+    CUSTOMER, VENDOR, ITEM, BANK, CATEGORY, TAX, CURRENCY,
     INVOICE, BILL, PAYMENT, TRANSFER,
-    CHART_OF_ACCOUNT, JOURNAL_ENTRY,
+    ACCOUNT, JOURNAL_ENTRY,
 ]
 
 BY_NOUN = {r.noun: r for r in RESOURCES}

{akt_cli-0.3.0 → akt_cli-0.4.0}/src/akt/resources.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass, field
 from typing import Any, Callable
 
 from .client import Client
+from .coa import resolve_coding
 
 
 # --------------------------------------------------------------------------
@@ -436,6 +437,18 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
     contact_id = getattr(ns, "contact_id", None)
     category_id = getattr(ns, "category_id", None)
 
+    coa = getattr(ns, "_coa", None)
+    account_ref = getattr(ns, "account", None)
+    de_account_id = None
+    if account_ref:
+        if coa is None:
+            raise ValueError(
+                "--account requires a COA config (pass --coa FILE or set AKT_COA_FILE)")
+        coa_de_account_id, coa_category_id = resolve_coding(coa, client, account_ref=account_ref)
+        de_account_id = coa_de_account_id
+        if category_id is None:            # explicit --category-id wins
+            category_id = coa_category_id
+
     if invoice_id:
         document = client.show("documents", invoice_id, type_scope="invoice")
         ptype = ptype or "income"
@@ -492,6 +505,8 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
         body["reference"] = ns.reference
     if getattr(ns, "description", None):
         body["description"] = ns.description
+    if de_account_id is not None:
+        body["de_account_id"] = de_account_id
     body.update(parse_set(getattr(ns, "set_", None)))
     body.update(load_data_arg(getattr(ns, "data", None)))
 
@@ -732,7 +747,7 @@ def _apply_sub_account(body: dict) -> None:
 def build_account_create(res: Resource, client: Client, ns: Any) -> dict:
     body = body_from_fields(res, ns, for_update=False)
     if not body.get("name"):
-        raise ValueError("--name is required to create a chart-of-account")
+        raise ValueError("--name is required to create an account")
     _apply_sub_account(body)
     return body