bus-entities — manage counterparty reference data
bus-entities — manage counterparty reference data
Synopsis
bus entities init [-C <dir>] [global flags]
bus entities list [-C <dir>] [-o <file>] [-f <format>] [global flags]
bus entities add --id <entity-id> --name <display-name> [-C <dir>] [global flags]
Description
Command names follow CLI command naming.
bus entities maintains counterparty reference datasets with stable entity identifiers used by invoices, bank imports, reconciliation, and other modules.
Entity data is schema-validated and append-only for auditability.
Commands
init creates baseline entity datasets and schemas. If they already exist in full, init warns and exits 0 without changing anything. If they exist only partially, init fails and does not modify files.
list prints the registry in stable identifier order. add appends a new entity record.
Options
add accepts --id <entity-id> and --name <display-name>.
list has no module-specific filters.
Global flags are defined in Standard global flags. For command-specific help, run bus entities --help.
Write path and field coverage
The CLI surface is intentionally small. bus entities add writes the stable entity identifier and display name, and it refuses to write rows that would violate schema or invariants.
If your entities.csv schema includes additional identity or bookkeeping columns (for example business identifiers, VAT numbers, country codes, payment identifiers, or default handling fields), those fields are currently edited by updating entities.csv directly and then validating the workspace with bus validate. This makes the “owner write path” explicit: bus entities owns the dataset, but not every column is maintained through flags.
Files
entities.csv and its beside-the-dataset schema entities.schema.json live in the accounts area at the workspace root, alongside other canonical datasets such as accounts.csv. The module does not create or use a dedicated entities/ subdirectory; layout follows the minimal workspace baseline and matches other BusDK modules. Path resolution is owned by this module; other tools obtain the path via this module’s API (see Data path contract).
Examples
bus entities init
bus entities add --id FI-1234567-8 --name "Acme Oy"
bus entities list --format tsv --output ./out/entities.tsv
Exit status
0 on success. Non-zero on errors, including invalid usage or schema violations.
Using from .bus files
Inside a .bus file, write this module target without the bus prefix.
# same as: bus entities add --id FI-7654321-0 --name "Northwind Oy"
entities add --id FI-7654321-0 --name "Northwind Oy"
# same as: bus entities list --format tsv
entities list --format tsv
Development state
Value promise: Maintain counterparty (entity) master data as schema-validated workspace tables so invoices, bank, and loans can reference stable entity identifiers.
Use cases: Accounting workflow, Sale invoicing (sending invoices to customers), Finnish payroll handling (monthly pay run).
Completeness: 50% — Init, add, and list are verified by e2e and unit tests; user can complete the counterparty master-data step for accounting, sale invoicing, and payroll.
Use case readiness: Accounting workflow: 50% — init, add, list verified; user can define counterparties. Sale invoicing: 50% — init, add, list verified; user can define customers. Finnish payroll handling: 50% — init, add, list and --id/--name verified by e2e; user can define party references for employees.
Current: Init/add/list and global-flag behavior are test-verified. Detailed test matrix and implementation notes are maintained in Module SDD: bus-entities.
Planned next: Expose Go library path accessors for entities dataset and schema (NFR-ENT-002, IF-ENT-002) so other modules obtain paths from this module; no use-case-specific next.
Blockers: None known.
Depends on: None.
Used by: bus-invoices and bus-loans reference entity data; bus-bank and bus-reconcile use counterparty identifiers.
See Development status.