xmatix scripts round-trips automation scripts — the C# bodies and their version state — so scripts can be edited in a real editor, versioned in git, and tested and observed from a terminal. Pushing never bypasses the platform's safety net: every pushed version is compiled on the server before it persists, and activation remains an explicit step.
xmatix scripts list
xmatix scripts pull --all # every script in the tenant
xmatix scripts pull <name> # a single script
xmatix scripts push <file.csx> # upload a new version
xmatix scripts push <file.csx> --activate # …and make it the active version
xmatix scripts run <file-or-name> --record <record-id>
xmatix scripts logs --script <name-or-id> --follow
xmatix runs tail --follow # cross-script run feedFile layout
Scripts land under xmatix/automation/scripts/, organized into a folder per entity (taken from the script's first binding; scripts with no binding go under _unbound/). Each script is a pair:
xmatix/automation/scripts/Account/MyValidation.csx # the source body
xmatix/automation/scripts/Account/MyValidation.meta.jsonThe .meta.json companion records the script id, name, label, description, current version and body hash, plus the binding metadata (lifecycle phase, change kinds, target entity, synchronous/asynchronous, order). Push reads it to attach the new version to the right script and to detect when nothing has changed; run reads it to default the entity and phase. Keep the pair together — a .csx without its sibling cannot be pushed.
Push: compile-validated versions
scripts push creates a new version on the server, which compiles the body before persisting. Compile failures print as diagnostics and exit non-zero — there is no separate dry-run verb because every push is already a server-validated dry run. Options:
| Option | Effect |
|---|---|
--activate | Make the new version the script's current (active) version — without it, the upload does not change runtime behavior |
-m, --message <text> | A comment stored against the version (a git SHA is a good habit) |
--force | Push even when the local meta hash no longer matches the server's current version — i.e. someone changed the script in the product since your last pull. Without --force the push stops so you can pull and reconcile first |
Run: server-side test dispatches
scripts run invokes the same test facility as the product's script editor — a real dispatch through the real pipeline, so data writes and messages are real; test mutating scripts against disposable records.
| Option | Effect |
|---|---|
-r, --record <guid> | The record to bind into the script's context (optional for server-action tests) |
-e, --entity <name> | Entity name; defaults to the first lifecycle binding's entity |
-p, --phase <phase> | LoadDefaults, PreValidate, Validate, BeforeSave, BeforeDelete, AfterSave or AfterDelete; default BeforeSave |
--action <name> | Test a server-action binding instead of a lifecycle phase (mutually exclusive with --phase) |
--change-kind <kind> | Insert, Update or Delete; default Update |
Logs and the run feed
scripts logs lists recent run rows — status, phase, entity, duration, run id and error — and xmatix runs tail is the same command scoped across all scripts, the terminal twin of the product's Runs tab:
| Option | Effect |
|---|---|
-s, --script <name-or-id> | Filter to one script |
--status <status> | Pending, Running, Succeeded, Failed or Cancelled |
-n, --top <count> | Rows to return (1–500, default 20) |
-f, --follow | Poll and stream only new rows (Ctrl+C to stop) |
--interval <seconds> | Poll interval with --follow (default 3) |
--detail <run-id> | Print the full JSON of a single run and exit |
--json | Emit raw JSON instead of a table |
A run that ended Cancelled is usually a validation script blocking a save on purpose — read the run detail before treating it as a failure.
Common questions
What is the recommended editing loop?
xmatix watch in one terminal, xmatix runs tail --follow in another, your editor in the middle. Watch pushes every save (compile errors surface immediately), the tail shows each run as it lands, and nothing goes live unexpectedly because activation is still your explicit call — during a hot iteration, keep the binding disabled in the product and re-enable when the fix verifies.
Why does push say the server version changed?
Because someone edited the script in the product since your last pull, and your .meta.json hash no longer matches the server's current version. That is a real conflict, not a nuisance check: pull the script, reconcile in git (the diff shows exactly what changed in the product), then push. Use --force only when you have decided your local file should win.
Where is the script API (Ctx) documented?
Inside the product: the Readme tab of the script editor is the complete, versioned reference for every context surface, with signatures, transaction rules and sandbox limits. The scripts quickstart is the conceptual map — bindings, phases, testing and run history — and everything it says applies unchanged to scripts edited through the CLI.