The xMatix CLI

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. It also builds and installs metadata packages. The CLI is an early (alpha) release; xmatix --version prints the version you have, and the pages in this section describe what that release does, including the places where it still falls short.

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 --skip scripts,dashboards,reports
xmatix scripts pull --all         # scripts are pulled separately
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

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 and 1 means at least one failure. In the current CLI release, two checks fail on a correct setup: api, because the CLI's identity call gets a 404, and scopes whenever scopes is left empty. So doctor exits 1 even when everything works. Read its token line rather than its exit code. Authentication explains both.

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 200

It watches .csx files under xmatix/automation/scripts/ and .json files under the rules, workflows, dashboards and reports folders, including subfolders. Each kind has a --<kind>/--no-<kind> switch (--no-scripts, --no-workflows, --no-dashboards, …) and all five are on by default. --debounce sets the quiet period in milliseconds — 400 by default, never less than 50 — so a burst of saves becomes one push per changed file. A folder that does not exist yet is listed as "not present, skipped"; if nothing is left to watch, the command stops with "Nothing to watch". Metadata files are not watched. 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. Any other shell name is refused with "Unknown shell".

Permissions

The CLI acts as the signed-in user, so it can do only what that user can do in the product.

A refused call shows as a 403 in the command's failure message. Grant access through the user's security profile — see the security model.

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.

Related topics

• CLI quickstart
• Authentication
• Workspace layout
• Metadata packages from the CLI
• CI recipes