Workflows in the CLI

xmatix workflows round-trips the definitions behind the visual workflow designer as one JSON file per workflow. Pull writes the complete definition — the full activity tree, not a summary — so pull → edit → push is loss-less; push creates or updates by definition id and gives you explicit control over whether the result is published.

xmatix workflows list
xmatix workflows pull                          # → xmatix/automation/workflows/<name>.json
xmatix workflows pull <name-or-definition-id>
xmatix workflows push <file.json>              # update if known, create otherwise
xmatix workflows push <file.json> --publish
xmatix workflows push <file.json> --no-publish
xmatix workflows push <file.json> --new        # force create even if the id matches

File shape

Each file mirrors the server's full workflow detail, so nothing is lost between pull and push:

{
  "definitionId": "…",
  "name": "OnboardCustomer",
  "description": "…",
  "version": 7,
  "isPublished": true,
  "root": { /* the full activity tree */ },
  "customProperties": { }
}

Files are named for the workflow's name; a workflow with an empty name falls back to its definitionId. The root activity tree is the designer's own persistence format — the same structure you build on the canvas — which makes targeted edits (a changed condition, a renamed step) reviewable in a git diff even though the tree is verbose.

Push semantics

If the file's definitionId resolves on the server, the push updates that definition, and the server increments the version automatically.
If there is no match — or you pass --new — the push creates a new definition.
Publish state: an explicit --no-publish wins over --publish; with neither flag, the file's isPublished value is preserved on update, and a newly created workflow defaults to draft.

The publish flags matter because of the designer's core rule: triggers only register from the published version. A pushed draft changes nothing at runtime until it is published — which is exactly what you want when promoting a reviewed change that a human should activate, and exactly what surprises you when you expected the push to go live. Decide per pipeline: --publish for environments where merge means live, no flag where publishing stays a deliberate in-product act.

Common questions

Why did my pushed workflow not fire?

Because it is a draft. Either the push created a new definition (drafts by default) or it updated one whose file had isPublished: false. Check the workflow's status in the designer — if it shows a newer draft than the published version, publish it (or push again with --publish). This is the single most common surprise in workflow round-tripping.

Can I edit the activity tree by hand?

Yes, with care — the tree is the designer's persistence format, and a structurally invalid edit will be rejected on push or misbehave in the designer. Hand-editing shines for mechanical changes: renaming an entity reference across many workflows, tweaking a literal, copying a step between definitions. For structural work, the visual designer is the better editor; the file is the better diff.

How do I copy a workflow to another tenant?

Pull it from the source workspace, then push the file from a workspace configured for the target tenant with --new (so it creates rather than trying to update a definition id that only exists at the source). References to entities and templates resolve by what exists in the target tenant — push the metadata first if the workflow depends on custom entities.