Business rules in the CLI

xmatix rules round-trips business rules as one self-describing JSON file per rule, organized by entity. Files carry the rule definition and its actions inline, so a rule reviews as a single unit in a pull request and pushes as a single unit to the server.

xmatix rules list                          # all rules
xmatix rules list --entity Account         # filter by target entity
xmatix rules pull                          # → xmatix/automation/rules/<entity>/<rule>.json
xmatix rules pull --entity Account
xmatix rules pull <rule-name>              # a single rule (case-sensitive)
xmatix rules push xmatix/automation/rules/Account/AutoApprove.json
xmatix rules push <file.json> --yes        # skip the confirmation prompt

File shape

Each file wraps the rule in an envelope naming its entity, so a push can resolve the target without any workspace state:

{
  "entityName": "Account",
  "rule": {
    "name": "AutoApprove",
    "label": "Auto approve",
    "description": "…",
    "isActive": true,
    "scope": 0,
    "triggers": 2,
    "conditionFormula": "…",
    "order": 0,
    "priority": 0,
    "stopOnFalse": false,
    "triggerFields": null,
    "actions": [ { "…": "…" } ]
  }
}

The rule object is the server's own representation — the same fields the rule editor writes — with actions inline in file order. Files are named <entity>/<rule-name>.json with filesystem-unsafe characters replaced.

Push semantics

rules push upserts by (entity, rule name):

The entity is resolved from the file's entityName; the push fails clearly if it does not exist on the target tenant.
If a rule with the same name already exists on that entity, it is updated in place — and its actions are replaced wholesale with the file's actions array (existing actions are removed, the file's are recreated in file order).
Otherwise the rule is created.

Two consequences worth internalizing. First, the file is the source of truth for actions — there is no partial-action merge, so never hand-edit one action on the server and one in the file and expect both to survive. Second, a file whose rule has no actions property leaves the server's actions untouched — the wholesale replacement only happens when the file states an action list. Because replacing actions is destructive, push asks for confirmation unless you pass --yes.

Common questions

How do I safely rename a rule?

Remember that push matches by name: pushing a file with a new name creates a second rule rather than renaming the old one. Rename in the product (or accept the create) and then delete the old rule deliberately — and re-pull afterwards so the file tree matches. The same applies to moving a rule between entities.

The rule pushed fine but never fires — why?

The usual suspects are the rule's own switches, faithfully round-tripped: isActive false in the file, a conditionFormula that never parses or never matches, or triggers that do not include the change kind you are testing. The product's rule editor and its test runner remain the best diagnosis tools — the CLI moves the definition around; the business rules page explains how the definition behaves.

Should rules be edited as JSON or in the product?

Both, for different jobs. The product's editor validates conditions as you type and previews behavior; JSON editing shines for review, bulk changes and promotion — the same rule applied to a second tenant, an action tweaked across twenty rules, a pull request that shows exactly which condition changed. Whichever side edits, pull after in-product changes and push after file changes, so neither side drifts.