CLI authentication

Q: How do I work with two tenants?

Use one workspace per tenant, each with its own .xmatix/config.json and its own tenant slug. Because the token cache is named by the slug, the two workspaces sign in and cache independently on the same machine. Run each command from inside the workspace for the tenant you mean, because the CLI always uses the nearest .xmatix/ folder above your current directory. Don't give two workspaces the same slug for different organizations: they would share one cache, and signing out of one would sign you out of both.

The xMatix CLI signs you in with a device code: xmatix login shows a web address and a short code, you finish signing in in any browser, and every later command calls the API as you. You sign in once per workspace after xmatix init and before your first pull, push or run. After that, commands refresh the session silently until it can no longer be renewed.

Overview

Three commands manage the session, and one command checks it:

xmatix login --tenant <tenant> --api-base-url <api-url> \
  --authority <authority-url> --client-id <client-id>
xmatix logout
xmatix whoami
xmatix doctor

login saves the connection settings into .xmatix/config.json and runs the device-code sign-in.
logout clears every cached sign-in for the workspace's tenant on this machine.
whoami is meant to show the tenant and the signed-in user. See Common problems for its current behaviour.
doctor checks the workspace, the config, a silent token and an API round trip.

The CLI never sees your password. Your organization's own sign-in page handles the credentials, with the same policies and verification steps as signing in to the product. The CLI receives only the resulting tokens.

When to use it

First use on a machine. Run the full login with all four connection flags, or a bare login if the repository already contains a filled-in .xmatix/config.json.
A command says to sign in again. Run a bare xmatix login; the stored settings supply everything except your credentials.
Handing a machine to someone else, or switching accounts. Run xmatix logout first, then sign in as the new user.
Pointing a workspace at a different API or sign-in authority. Run logout, then login with the new flags.

How xMatix handles it

Which workspace a command uses

Every command looks for the nearest .xmatix/ folder, starting in the current directory and walking up through its parents. That folder's config.json decides where the command connects. login is the one exception: if it finds no .xmatix/ folder it creates one in the current directory and writes the config there. Run xmatix init first, from your repository root, so the workspace also gets its .gitignore, folders and editor tasks.

It reads the existing config, if there is one, and overrides it with any flags you passed.
If the tenant, API base URL, authority or client id is still empty, it stops with Missing config. and exits 1.
It writes the merged settings to .xmatix/config.json. This happens before sign-in, so a mistyped value is saved even if the sign-in then fails.
It prints the workspace path, the tenant and the API base URL, then the sign-in instructions: a web address and a one-time code.
You open the address in any browser (another computer or a phone works too), enter the code and sign in.
The CLI prints Signed in as with your user name and Token expires: with the token's expiry time in UTC. It exits 0.

If anything in steps 4 to 6 fails, the CLI prints Login failed: with the reason and exits 1.

Where tokens are kept

Tokens never go into the repository. They are cached in your home directory under .xmatix/tokens/<tenant>/, and the operating system's secure storage protects them:

Operating system	Protection
macOS	The login keychain, in one entry per tenant slug
Windows	Windows data protection (DPAPI) for your user account
Linux	The desktop keyring (secret service), in one entry per tenant slug labelled as the CLI's token cache

The cache is named by the tenant slug alone. Two workspaces on one machine that use the same slug share one cache, and signing out of one signs out of both.

How a command gets its token

Each command takes the first account in the tenant's cache and asks for a token silently, renewing it when needed. With no cached account, it fails with No cached account; run xmatix login first. When renewal is no longer possible (for example after a long idle period, a password change or a revoked session), the command fails with the sign-in service's reason, and a bare xmatix login fixes it.

The token is requested for the scopes in the config. When scopes is empty, the CLI uses one scope built from the API base URL: <api-url>/.default.

Which organization a command acts on

The API base URL decides the organization. The CLI sends no separate tenant identifier with its calls, so the tenant slug in the config only names the token cache and appears in command output. If the slug and the API base URL point at different organizations, commands act on the organization of the API base URL.

Prerequisites

The CLI installed (see the CLI quickstart) and a workspace created with xmatix init.
An xMatix user account that can sign in to your organization. The CLI acts with exactly that account's permissions.
The four connection values from your xMatix administrator: tenant slug, API base URL, sign-in authority URL and the CLI's client id. None of them is a secret.
A browser on any device, to complete the device-code sign-in.
On Linux, a running secret service (keyring) for your user, because the token cache is stored there.

Procedure

From the repository root (the folder that contains .xmatix/), run:

xmatix login --tenant <tenant> --api-base-url <api-url> \
  --authority <authority-url> --client-id <client-id>

Add --scopes "<scope> <scope>" only if your administrator gives you specific scopes. Open the address the CLI prints, enter the code and sign in as yourself. The CLI then shows Signed in as with your user name.

If the repository already holds a filled-in .xmatix/config.json, for example because a teammate committed it, a bare xmatix login is enough.

Step 2 — Check the session

Run xmatix doctor. Look for a tick on token (it reads "acquired silently" with the expiry time). See Common problems for the two checks that currently fail on a correct setup and how to read them. To prove a real API round trip, run a read-only command such as xmatix scripts list.

When a command fails because no token could be obtained, run a bare xmatix login. The flags are not needed again: they were saved in step 1.

Step 4 — Switch to a different user

Run xmatix logout. It prints Cleared cached tokens for tenant with the slug.
Run xmatix login and sign in as the other user.

Always sign out first. login adds the new account to the cache but does not remove the old one, and commands use the first cached account, which can still be the earlier user.

Step 5 — Point the workspace somewhere else

To change the API base URL, authority, client id or scopes:

Run xmatix logout, so no token issued for the old settings is reused.
Run xmatix login with only the flags that change. Flags you leave out keep their stored values.

Step 6 — Sign out of a machine

Run xmatix logout from inside the workspace. It removes every cached account for that tenant slug and leaves config.json unchanged. Run outside any workspace, it prints No workspace config found; nothing to do. and changes nothing.

Fields

The workspace config, .xmatix/config.json:

{
  "tenant": "<tenant>",
  "apiBaseUrl": "<api-url>",
  "authority": "<authority-url>",
  "clientId": "<client-id>",
  "scopes": "",
  "apiVersion": "v1"
}

Setting	What it means	Notes
`tenant`	Your organization's tenant slug	Required. Set with `--tenant` (or `-t`). Names the token cache; it does not choose the organization the API acts on
`apiBaseUrl`	Base URL of your organization's xMatix API	Required. Set with `--api-base-url`. Decides which organization every command acts on
`authority`	Your organization's sign-in authority URL	Required. Set with `--authority`
`clientId`	The registered client id of the CLI application	Required. Set with `--client-id`
`scopes`	The scopes the token is requested for	Optional. One text value, space-separated, not a list. Set with `--scopes`. When empty, the CLI uses `<api-url>/.default`
`apiVersion`	The version segment the CLI puts in API routes	Defaults to `v1`. `login` has no flag for it; edit the file only if your administrator tells you to

Business rules

login needs a tenant, an API base URL, an authority and a client id, taken from flags or the stored config. Without all four it exits 1 and nothing is signed in.
Flags passed to login always replace the stored values and are saved before sign-in starts.
The token cache is per tenant slug and per operating-system user. It is never inside the repository.
Commands use the first cached account for the tenant. logout clears all of them.
logout never edits config.json, and login never removes cached accounts.
Only device-code sign-in is available. The CLI has no service-principal, client-secret or environment-variable sign-in.

Example

A developer joins a team whose repository already has a committed .xmatix/config.json:

They clone the repository and run xmatix login in its root.
The CLI prints the workspace, tenant and API, then a web address and a code. They open the address on their phone, enter the code and sign in with their own work account.
The terminal shows Signed in as with their address and a token expiry time.
xmatix doctor shows ticks for workspace, config, authority, client id and token. It shows a cross for scopes (the committed file leaves it empty) and for api.
They run xmatix scripts list and see the organization's automation scripts, which proves the API accepts their token.
Two weeks later a pull fails because the session can no longer be renewed. A bare xmatix login fixes it.

Training

Practice exercise

In a sandbox workspace:

Run xmatix init, then xmatix login with the four connection flags your trainer gives you. Expected: Signed in as with your user name.
Open .xmatix/config.json and confirm that it holds the four values, with scopes empty.
Run xmatix doctor. Expected: a tick on token and a cross on scopes.
Set "scopes" to the API base URL followed by /.default and run doctor again. Expected: scopes now has a tick.
Run xmatix logout, then xmatix scripts list. Expected: it fails with No cached account; run xmatix login first.
Run a bare xmatix login and repeat scripts list. Expected: the list appears.

Quick reference

First sign-in: login with --tenant, --api-base-url, --authority, --client-id.
Later sign-ins: a bare login.
Switching user: logout, then login.
Tokens live in your home folder under .xmatix/tokens/<tenant>/, protected by the OS.
config.json holds no secrets and can be committed.
The API base URL decides the organization; the slug only names the cache.
scopes is one space-separated text value.
Device-code sign-in is the only method.

Permissions

The CLI has no permissions of its own. Every call runs as the signed-in user, so a command can see and change exactly what that user can in the product, and the server records the user as the one who made the change. When a user lacks access to an area, the server refuses or limits that command. To give someone CLI access, give their user account the access they need in the product. Avoid shared accounts: they erase the audit trail and usually hold more access than any one person needs.

Configuration

An administrator sets up CLI access once per organization:

Hand out the four connection values: tenant slug, API base URL, sign-in authority URL and the CLI's client id. They are the same for every developer in the organization.
Commit the config to the team's repository, so each developer needs only a bare xmatix login. The file holds no secrets. The .gitignore that xmatix init creates keeps cache and token folders out of commits.
Set scopes explicitly to the API base URL followed by /.default, the same value the CLI uses when it is empty. With it set, xmatix doctor stops reporting a scopes failure.
For automated jobs, use a persistent runner with access control, on which a person completes xmatix login once. The cache then serves later jobs on that runner while the session can still be renewed. The CI recipes page covers this pattern.

Common problems

`whoami` says "whoami failed" with a 404

In the current CLI release, whoami calls the identity endpoint without the API version segment, and the API does not serve that address. The command prints the tenant and API from your config, then fails and exits 1. Your sign-in is not the problem. The Signed in as line from login shows the account. doctor's token line shows whether a silent token is available. A read-only command such as xmatix scripts list confirms the API accepts the token.

`doctor` always ends in "problem(s) detected"

Two checks currently fail on a correct setup. The api check uses the same identity call as whoami, so it fails with a 404. The scopes check fails whenever scopes is empty, even though an empty value works. Set scopes to the API base URL followed by /.default to clear the second one. Until the first is fixed, doctor exits 1, so don't use its exit code as a pass/fail gate; read the token line instead.

The tenant, API base URL, authority or client id is missing from both your flags and .xmatix/config.json. Check that you are inside the right workspace, because login uses the nearest .xmatix/ up the folder tree. Then run the full login with all four flags once.

"No cached account; run `xmatix login` first."

This tenant slug has no sign-in on this machine: first use, after logout, or on a new machine or runner. Run xmatix login.

Commands still act as the previous user

You signed in as a second user without signing out first, so the cache holds both accounts and commands use the first one. Run xmatix logout, then xmatix login as the user you want.

A bare `login` keeps failing after an earlier failed sign-in

Flags are saved before sign-in starts, so a mistyped value from the failed attempt is still in config.json, and every bare login reuses it. Open .xmatix/config.json, check all four values, correct the wrong one (or pass it again as a flag), then run login.

The CLI can't read `config.json` after a hand edit

scopes must be one text value, such as "scopes": "<scope> <scope>", not a list in square brackets. Fix the value, or run login --scopes "<scope>" to rewrite it.

Commands act on a different organization than the slug suggests

The API base URL decides the organization, and the slug only names the cache. Correct apiBaseUrl, then run logout and login so you get a token for the right API.

Common questions

How do I work with two tenants?

Use one workspace per tenant, each with its own .xmatix/config.json and its own tenant slug. Because the token cache is named by the slug, the two workspaces sign in and cache independently on the same machine. Run each command from inside the workspace for the tenant you mean, because the CLI always uses the nearest .xmatix/ folder above your current directory. Don't give two workspaces the same slug for different organizations: they would share one cache, and signing out of one would sign you out of both.

No. Device-code sign-in is the only method the CLI offers, and it always needs a person to enter the code in a browser. The CLI does not read credentials from environment variables, and it has no service-principal or client-secret sign-in. The working pattern is a persistent runner with access control, on which someone runs xmatix login once. Later jobs reuse that cache while the session can still be renewed. When it can't, a person signs in on the runner again. See CI recipes.

Is it safe to commit `.xmatix/config.json`?

Yes. It holds the tenant slug, two URLs, a client id, the scopes and the API version, and none of them is a secret. Tokens are kept in your home folder, protected by the operating system, and never in the repository. Committing the config is the easiest way to give a whole team the same working setup. Each person still signs in as themselves, so the server records who made each change.

The CLI acts with the signed-in user's permissions, and the platform records who did what. A shared account erases that record and usually holds more access than any one person needs. Individual sign-in costs nothing extra: the committed config is shared through the repository, and only the sign-in itself is personal.