xmatix is a single command-line tool that gives developers a git-friendly, round-trippable view of every customizable artifact in a tenant: automation scripts, business rules, workflows, dashboards, reports and metadata. Each artifact kind has pull and push verbs that write to and read from a canonical folder tree, so a tenant's configuration can live in a repository, travel through pull-request review, and be promoted by pipeline. The CLI is currently in preview: commands and file formats are stable enough to document, but expect the tool to evolve.
Before a CLI change, run xmatix doctor, pull the current tenant state, review the diff and preserve the server version or hash used for optimistic concurrency. After a push, verify the artifact's status and active version in its product workspace and inspect run history rather than assuming upload equals activation.
Install and first run
The CLI ships as a .NET global tool and runs anywhere the .NET 10 SDK does:
dotnet tool install -g xmatix.cli
xmatix init # scaffold the workspace in your repo root
xmatix login --tenant <tenant> \
--api-base-url <api-url> --authority <authority-url> --client-id <client-id>
xmatix doctor # pre-flight checks
xmatix snapshot export # pull everything
git add xmatix/ && git commit -m "tenant snapshot"init creates the .xmatix/ config directory and the folder tree; login runs a device-code sign-in and persists the connection settings (they are only needed once — see Authentication for where each value comes from); doctor verifies everything before you rely on it. The quickstart walks this first session end to end.
Command map
| Command | What it does | Reference |
|---|---|---|
login / logout / whoami | Device-code sign-in, cached-token cleanup, current identity | Authentication |
init / doctor | Scaffold the workspace; run every pre-flight check | Workspace layout |
metadata pull / push / diff | Round-trip tenant metadata seed-packs | Metadata |
scripts list / pull / push / run / logs, runs tail | Round-trip automation scripts, test them, tail run history | Scripts |
rules list / pull / push | Round-trip business rules, one file per rule | Business rules |
workflows list / pull / push | Round-trip workflow definitions | Workflows |
dashboards / reports list / pull / push | Round-trip analytics definitions | Dashboards & reports |
snapshot export / import | Pull or push every artifact kind in one command | Snapshots |
migrate plan / apply | Diff the repo against the live tenant; promote the reviewed state | Migrations |
package init / build / validate / install / list / logs / uninstall | Author and install metadata packages (manifest + seed-packs) | — |
watch | Auto-push files as you save them | below |
completions | Emit a shell completion script | below |
Utilities
xmatix doctor
Runs every check the other commands assume: the workspace root resolves, config.json is readable and complete (authority, client id, scopes), the canonical folders exist (missing ones are noted as "created on first pull"), a token can be acquired silently, and a whoami round-trip against the API succeeds. Exit code 0 means healthy, 1 means at least one failure — run it as the first step of every pipeline job so auth, network and config drift fail fast with a named cause.
xmatix watch
Watches the round-trip folders and re-runs the matching push on every save — the tight loop for local development of scripts, rules and workflows:
xmatix watch # all artifact kinds
xmatix watch --no-rules --no-reports
xmatix watch --debounce 200Each kind has a --<kind>/--no-<kind> switch (--no-scripts, --no-workflows, --no-dashboards, …) and --debounce sets the quiet period in milliseconds. Every save spawns a child xmatix … push process, so one failing push never tears the watcher down; child output is forwarded indented so the stream stays readable. Ctrl+C exits cleanly.
xmatix completions
Emits a static completion script for bash, zsh, fish or pwsh — for example xmatix completions zsh — which you redirect into your shell's completions location. The script is static, so completion never invokes the CLI at prompt time.
Common questions
Is the CLI required to use automation scripts, rules or workflows?
No. Everything the CLI round-trips is fully authorable inside the product — the CLI's value is the representation: real files in a real repository, diffable in pull requests, promotable by pipeline, and editable in your own editor. Teams typically start in the product and adopt the CLI when a tenant's configuration becomes something they want to review and release like code.
What is safe to commit?
Everything the CLI writes except caches and tokens. The xmatix/ artifact tree and .xmatix/config.json are designed to be committed — the config file holds connection settings, never credentials. Sign-in tokens are cached per user in your home directory, encrypted by the operating system's credential store, and never land in the repository; init also writes a .gitignore inside .xmatix/ as a belt-and-braces guard.
Which platforms does it run on?
Anywhere the .NET 10 SDK runs — the token cache uses the platform's native secure storage on each OS (keychain on macOS, DPAPI on Windows, the keyring/secret service on Linux), so no platform needs special handling.