CLI

The xema CLI is the single, multi-platform command-line entry point to Xema. It boots a local platform, scaffolds and validates biomes, installs them, invokes capabilities, drops you into the Shell, and runs diagnostics. The same binary works against a locally-booted platform, a self-hosted single-VM deployment, and a multi-node cluster.

Install

1npm install --global @xemahq/xema
2# or
3pnpm add --global @xemahq/xema

Verify

1xema --version
2xema doctor

xema doctor checks the local substrate: node version, the ~/.xema/ config directory, the resolvable distribution editions, the license in force and what it entitles, the container runtime and its platform, free disk space, the host ports a launch publishes, and container-registry reachability. Every check is reported — a check that cannot be evaluated says so explicitly rather than passing quietly.

1xema doctor                 # the local environment
2xema doctor --infra         # also TCP-probe the relational database, Redis, etcd, the platform event bus, …
3xema doctor --sources       # list the configured biome sources + whether their tokens are present

Developer mode

The platform-contributor command xema up is hidden from --help unless developer mode is on. It still runs if invoked directly.

1xema config set dev on      # persisted to ~/.xema/config.yaml
2xema config get             # shows whether it is active, and why

The XEMA_DEV environment variable overrides the persisted setting at runtime.

Commands

Every command takes --help.

xema up

Boot the platform with one command. Resolves the distribution lock plus xema.config.yaml into an effective roster, brings up managed infrastructure, and supervises the service waves over the configured substrate (container or native). Foreground by default.

On the container and helm substrates, --release-list <file> is required: the seed image boots at the digest the release list froze, and the list's biomes install afterwards with xema distribution apply. On helm, --chart-set <file> names the chart-set lock, and it must be the one the list froze. Native boots no seed image and needs no list.

The release list must agree with the edition's locks. xema up resolves the tag the edition's images lock pins for the seed and refuses the boot when that digest is not the list's seed digest. It prints xema up failed: followed by seed <repository>: release list <digest>, edition lock <digest>, naming both values and choosing neither. On helm, the release list is the one chart-set authority: the --chart-set file must hash to the list's chartSet, or it is refused as chart set: release list <digest>, --chart-set <digest>, and the verified file is what helm installs from. No other chart-set lock on the machine (an install context's lock or XEMA_CHART_SET_LOCK) is read. --dry-run runs the same seed check before it prints. A verified chart set installs only from its OCI digests, so --chart-set is refused when the charts directory the CLI would use, XEMA_CHARTS_DIR or the install context's charts/ folder, holds any local chart (a <name>-<version>.tgz or a <name>/Chart.yaml); the error names the directory and the charts it found.

--mirror-config <file> (with delivery: relay) copies the release list's seed image to the target registry before the start, so it needs --release-list; without one it is refused, and on native it is refused because native runs no seed image.

The edition is always named, in xema.config.yaml (edition:) or with --edition; there is no default edition.

1xema up
2xema up --edition appliance-base --release-list release-list.json
3xema up --only workflow-engine-api      # plus that service's hard prerequisites
4xema up --dry-run                       # print the resolved roster, waves and ports; boot nothing

xema down stops what up started.

xema distribution apply

Converge a Biome Host to a frozen package list and report, per biome, whether it serves. It plans, applies the plan, follows the progress stream until it completes, fails or --ready-within passes, then reads serving status once. There is no polling loop.

1xema distribution apply --list packages.json --ready-within 600 \
2  --host https://biome-host.example.com --client-id apply-client \
3  --client-secret-file ./apply-client.secret \
4  --token-endpoint https://identity.example.com/token

The secret is read only from the file, never from the command line. The file must not be readable by group or others (mode 0600); the command refuses a more open file and names the path, never the content. --token-endpoint must be https; plain http is accepted only for a loopback host (localhost, 127.0.0.0/8, ::1), because the endpoint receives the secret.

Exit codes:

The JSON result lists one entry per listed biome, in list order, then unlisted ones sorted by biome. Each entry has a status:

• ready: the biome serves, and the digest it serves is the planned digest. The reported digest is the serving digest.
• not-ready: the biome does not serve yet. The reason says why, for example serving failed: <detail>, pending (<state>), not installed, or serving-digest-mismatch: serving <A>, planned <B> when it serves a different digest than planned.
• refused: the plan or the apply refused or excluded the biome, with reason as <code>: <detail>.
• unlisted: the plan touches a biome the list does not name.

xema distribution snapshot

Freeze the serving environment into a release list: every bundle biome at its serving digest, the seed image and the chart set. It is all or nothing: if any biome is not serving or has no digest, or the environment reports no seed, nothing is written and each offending biome is printed on its own stderr line.

1xema distribution snapshot --edition appliance-base --chart-set chart-set.lock.json \
2  --out release-list.json --host https://biome-host.example.com \
3  --client-id apply-client --client-secret-file ./apply-client.secret \
4  --token-endpoint https://identity.example.com/token

The seed repository comes from the edition's images lock, the same reader xema up uses. The chart set must be the one the environment reports: the digest of the --chart-set lock must equal the digest of the chart set in the environment's seed block, and a mismatch is refused with both digests named. A seed block whose chart set is not a chart-set lock is refused too. The list is written to a temporary file next to --out and renamed onto it, and the temporary file is removed if the write fails.

Exit codes: 0 on success, 1 when the environment cannot be frozen (including a chart-set mismatch), 2 on a usage error, 3 when Biome Host or the token endpoint is unreachable, 4 when the credentials are refused.

xema biome scaffold <name>

Generate a new, valid biome directory — manifest, one example contribution, and the boundary-check config, so the new biome passes lint out of the box.

1xema biome scaffold hello-xema
2xema biome scaffold hello-web --target web --scope platform

xema biome validate [path]

Run the pre-boot checks over a biome directory — manifest schema, xema.agents[] ⟷ agents/*.md parity, contribution envelopes, skill frontmatter, workflow schemas — without booting anything. Defaults to the current directory.

1xema biome validate
2xema biome validate ./my-biome

Exits 0 when every check passes and non-zero when one fails, listing every issue rather than only the first — so it drops straight into CI.

xema biome dev [path]

The biome sandbox loop: the same validation pass, then overlay the directory as a workspace source (no publish, no token) and boot the smallest platform slice the biome needs.

1xema biome dev
2xema biome dev --dry-run       # validate + print the resolved slice, boot nothing

A workspace source always outranks every remote source for the same biome. That is what lets xema biome dev run local edits with no publish and no registry token.

xema biome search|list|info

Browse the Store catalog.

1xema biome search "code review"
2xema biome list --trust-tier first-party
3xema biome info <listingId>

xema biome install <biomeId>

Install a catalog biome into a running platform, or fetch it to this machine so xema up can boot it without a platform at all.

1xema biome install acme-code-review --org <orgId>
2xema biome install acme-code-review --local --from my-registry

The install goes through Biome Host's lifecycle door: it plans the install (dependencies, permission digest, capability registration), shows the plan, and applies exactly what was planned. Configure the installation afterwards through its settings. xema biome uninstall <biome> uninstalls it through Biome Host (plan, confirm, streamed progress) and keeps the biome data unless you pass --purge.

xema biome publish <path>

Package the biome as an OCI artifact, push it (oras push), then sign the pushed ref (cosign sign).

1COSIGN_KEY=cosign.key xema biome publish ./ --registry ghcr.io/acme --token-env GHCR_TOKEN
2xema biome publish ./ --keyless \
3  --certificate-identity https://github.com/acme/biomes/.github/workflows/publish.yaml@refs/heads/main \
4  --certificate-oidc-issuer https://token.actions.githubusercontent.com   # what CI should use
5xema biome publish ./ --dry-run                # print the resolved plan and the exact oras/cosign commands

Signing is mandatory. There is no unsigned mode. --keyless requires the run's own signer identity (the workflow file that runs, which is the reusable one when there is one) and its issuer. A publish owes a signature and an attestation by that signer: if the tag already holds the same content, signed only by another identity, it signs and attests the existing digest without pushing again. The identity flags are refused without --keyless; in key mode a dry run of an existing tag needs COSIGN_KEY. See SDK — Publishing for the full flag set.

xema biome submit <path> submits a published artifact to your org's private Store catalog.

xema biome lint

Run boundary and manifest checks across the workspace.

1xema biome lint
2xema biome lint --strict

xema run <capabilityRef>

Invoke a capability through the platform's capability router (POST /capabilities/invoke).

1xema run hello:greet@1 --input '{"name":"Ada"}'
2xema run kb:page.read@1 --input @page.json
3xema run shell:concepts.list@1

Capability refs such as hello:greet@1 are illustrative: they are invented to teach the syntax and no platform service produces them.

The acting subject is always the token's sub claim — it cannot be overridden. The environment defaults to environment:project and is set with --environment. The full result (allow / denial / audit id) prints as JSON, and a denied invocation exits non-zero so scripts can branch.

xema shell

An interactive REPL over the same router. Each line is <capabilityRef> [inputJson].

1xema shell
2> shell:ls@1 {"path":"/orgs/acme/projects/billing"}
3> shell:explain@1 {"ref":"xema://biomes/acme-code-review"}

Built-ins are help and exit / quit; Ctrl-D exits. Only an unreachable router at startup is fail-fast — an invocation error prints and the loop continues.

xema canopy

A conversational REPL over Canopy, the universal Xema agent. Where xema shell expects an exact capability ref on each line, you describe what you want in plain language and Canopy finds the capability, checks it can run it, and runs it.

1xema canopy
2xema canopy --org acme --environment project

On start the command opens, or resumes, your Canopy conversation and prints nothing from earlier turns. Each line you type is sent as one turn and the reply prints when it lands. If the turn is accepted but has not answered yet, the REPL says so and you can keep typing. A denied turn prints the audit id rather than a reason; look the decision up by that id. exit or quit leaves the REPL. The command exits with an error if the platform has no Canopy or your subject cannot see it.

xema objects list|get

Browse the typed object universe.

1xema objects list --space xema://orgs/acme/projects/billing
2xema objects list --type skill --limit 50
3xema objects get xema://orgs/acme/skills/release-notes

xema plan|apply|export|import

Declarative provisioning. See Xema-as-Code.

Other commands

Command reference

Generated from the CLI itself. Developer-mode commands are hidden from --help and are not listed.

Common workflows

Authoring a biome end-to-end

1xema biome scaffold my-biome
2cd my-biome
3# edit ./contributions, ./agents, ./skills, ./api...
4xema biome validate
5xema biome lint
6xema biome dev                        # boot the smallest slice that runs it
7xema biome publish ./                 # ship it

Working against a running platform

1export XEMA_ENDPOINT=https://xema.acme.dev
2xema login
3xema run kb:page.read@1 --input '{"pageId":"…"}'
4xema shell

Configuration

Persisted CLI settings live in ~/.xema/config.yaml; the login session lives in ~/.xema/session.json (owner-only). Platform configuration — the roster, biome sources, the edition — lives in xema.config.yaml, resolved through the standard search order or named with --config.

Connection details resolve identically for every command that talks to a platform:

A private biome source names the environment variable that holds its token (authTokenEnv) — the secret is never written into xema.config.yaml. A variable that is named but unset fails fast; it never falls through to an unauthenticated request.

Related concepts

• Capabilities — xema run invokes through the same surface.
• Shell — xema shell speaks the same capability surface the web terminal exposes.
• Biomes — xema biome commands manage the lifecycle.
• Xema-as-Code — xema plan / apply / export / import drive declarative provisioning.
• SDK / Getting Started — the end-to-end walkthrough.

Previous: ← Developer Annotations Next: Xema-as-Code →