@xemahq/xema

The Xema OS command-line interface

Overview

The single global binary for Xema. Install it once to launch the whole platform with one command, author and ship biomes, and invoke capabilities from your terminal.

xema up resolves the platform's distribution lock into an effective service roster, brings up the backing infrastructure you don't already run, and supervises every service to readiness — over a container substrate (customers) or a native substrate (contributors). It is a thin bring-up coordinator: it resolves topology and sequences startup, delegating process lifecycle (restart, health, resource limits) to the substrate beneath it (Docker/Podman, or your own infra). It never becomes a second orchestrator.

Installation

npm i -g @xemahq/xema

Scaffold a config — xema init

Generate a xema.config.yaml tailored to your scenario. Run it with no flags for a short interactive wizard, or --preset / --yes for scripted use:

xema init                                  # interactive wizard
xema init --preset local-container --yes   # full local stack in containers
xema init --preset byo-infra               # bring-your-own Postgres/Keycloak/object-store
xema init --preset appliance               # Kubernetes via Helm
#   --edition <id> picks a distribution edition (offered from xema-distributions);
#   --web enables the host shell; --output <path>; --force to overwrite.

The wizard walks you through:

• scenario (containers / BYO-infra / appliance),
• edition — which biomes make up the platform (oss, core, … described inline),
• infrastructure, per service — for each of Postgres / Redis / Keycloak / object-store / etcd / search / Temporal, choose auto (xema launches it) or external (paste your connection URL), and each external URL is connection-tested (reachability),
• your own biomes — add git repo(s) as sources (composed with the edition at launch), or use xema dist build for a full custom distribution.

Every generated config is validated against the schema before it's written, so it can never be one xema up would reject.

Launch the platform

xema up                    # boot the backend (infra + services) as one supervised process
xema up --web              # also start the host-shell frontend
xema up --all              # everything, including the frontend
xema up --detach           # leave container workloads running and return
xema down                  # stop everything (xema down --purge also deletes data volumes)
xema status                # show launcher-owned workloads + health
xema logs <service> -f     # stream a service's logs

Topology — xema.config.yaml

The launcher reads an optional xema.config.yaml (or ~/.xema/config.yaml) declaring which infrastructure you own and what to run. Every backing component is managed (the launcher starts it), external (you already run it — provide the URL), or disabled:

edition: oss
infra:
  postgres:    { mode: managed }
  redis:       { mode: managed }
  etcd:        { mode: managed }
  keycloak:    { mode: external, url: https://sso.corp/realms/xema, realm: xema }
  objectStore: { mode: external, url: https://s3.corp }
  search:      { mode: managed }
  temporal:    { mode: managed }
app:
  substrate: container        # container | native
  include: [ all ]            # all | <tier> | [service ...]
  features: []                # curated capability bundles
  web: { enabled: true }

• container (recommended): pulls content-addressed service images (imageRef:contentHash) and runs them on a shared network, after bringing up and bootstrapping managed infra — works without a monorepo checkout.
• native: runs services as host processes against a built monorepo (the contributor inner loop). Equivalent: xema serve --profile single-instance.
• helm: deploys to Kubernetes via helm upgrade --install (the appliance / cluster target). Equivalent: xema serve --profile appliance.

xema up fails fast on a missing required secret, an unreachable external dependency, or a disabled-but-mandatory infra component — never a silent degradation.

Realtime dev

Xema always runs the distributed model: every service is its own process and peers discover each other through the KernelState adapter over etcd (native forks one child per service; container/helm run one workload each).

For development, see code changes live — the composition restarts when service output changes (pair with each service's own tsc -w / turbo watch):

xema dev --watch           # boot from source; restart on any .ts change

Launch one service (or a subset)

Boot just the services you're working on — their hard prerequisites (identity-api, the foundational services) are pulled in automatically, so a lone service still boots a correct graph:

xema dev agent-session-api memory-api     # native: just these two (+ prerequisites)
xema up   --only app-runtime-api          # container: one service (+ prerequisites)
xema serve --profile cluster --only audit-log-api

Biome sources — pull biomes from many origins

A deployment's biomes can come from the first-party distribution, a cultivars edition, a client's own private git repo or registry, or a third party — each with its own auth — declared in a sources: block:

sources:
  - name: workspace                       # local working tree (monorepo): always wins
    kind: workspace
  - name: cultivars                       # a pinned edition lock
    kind: distribution
    edition: cultivars
  - name: acme                            # a client's OWN biome git repo (private)
    kind: git
    url: https://github.com/acme/xema-biomes.git
    ref: v2.1.0
    authTokenEnv: GIT_TOKEN_ACME          # env-var NAME, never the secret

Precedence: workspace > other sources (declared order) > base distribution. In a monorepo checkout the workspace source always wins, so xema dev runs your local edits with no publish and no token required. Tokens for private sources are referenced by env-var name (the biome-fetcher convention) and resolved from the environment or a git-ignored ~/.xema/credentials.env — never inlined in config. npm/oci sources are install-time (the xema biome install path); workspace/distribution/git boot directly from xema up/dev.

Check every source + token before launching:

xema doctor --sources       # per source: target, launch-vs-install, token present? (redacted)

A full example lives at examples/06-biome-sources.yaml.

The standard biome structure (one shape, open features)

Sources discover biomes by walking for xema-biome.json — a repo may hold ONE biome at its root or MANY nested; both are valid layouts of the same standard. A biome is a directory with a manifest at its root; its services live at the manifest-declared ships.apis[].path (convention ./api/<name>). What a biome does (services, skills, capabilities, agents) is wholly open — only the bundle shape is standardized, so every author builds the same way and any source resolves the same way.

Compose a distribution — xema dist build

Build your own platform: take a base edition's first-party biomes and add the ones you bring (your git repos / workspace dirs). The composition is validated by the real distribution resolver (dependency closure + trust + operator rules), then written as a distribution + a launch config:

xema dist build --id acme-platform --base oss \
  --git acme=https://github.com/acme/xema-biomes.git \
  --source local=./my-biomes \
  --config-out acme.config.yaml
#   or read sources from an existing config:  --config xema.config.yaml
#   --no-allow-third-party rejects non-first-party biomes (default: allowed)

It writes ~/.xema/distributions/<id>/{xema-distribution.json,distribution.lock.json} (the composed recipe + resolved record) and, with --config-out, a xema.config.yaml (base edition + your sources). Then:

xema dev --config acme.config.yaml   # native — your biomes run from source
xema up  --edition acme-platform     # first-party biomes by edition (your composition)

Your composed distribution also shows up as an edition in xema init and xema up --edition <id>. User biomes are third-party by origin and launch via the source registry (which resolves their source roots); building container images for your own biomes is a separate step.

Author biomes & run capabilities

xema dev                    # lock-driven native dev boot (contributors)
xema biome scaffold <name>  # author a new biome
xema biome publish <path>   # ship a biome
xema run <capability>       # invoke a capability by name
xema doctor                 # diagnose your environment

Install a catalog biome into a running platform (by id — the biome's bundle source is resolved server-side from its registered manifest; npm/OCI biomes require a project):

xema biome install <biomeId> --project <projectId>   # npm/OCI + any catalog biome
xema biome install <biomeId> --org                   # in-process / kernel biomes only
#   target + auth: --endpoint/--token or env XEMA_ENDPOINT / XEMA_TOKEN
#   --config <file.json> for install config, --version <semver> to pin

The CLI never sends a registry token: a private source's authTokenEnv is read by biome-fetcher-api in the platform's own environment, so the token lives on the cluster, not in the install call.

Xema-as-Code — declarative stacks

Drive a running control plane from a xema.yaml manifest (orgs, roles, deliverable-specs, biome-installs, …) — plan/apply/export/import, GitOps-style:

xema plan   -f xema.yaml                 # preview the change set (read-only)
xema apply  -f xema.yaml                  # apply it (--auto-approve to skip the prompt)
xema export --stack <name> -o xema.yaml   # snapshot a live stack to a manifest
xema import -f xema.yaml                   # adopt existing resources into a stack
#   target + auth: --endpoint/--token or env XEMA_ENDPOINT / XEMA_TOKEN

Diagnose

xema doctor                 # node version + ~/.xema/ + dev KernelState
xema doctor --infra         # also TCP-probe Postgres / Redis / event-hub-api
xema doctor --sources       # list biome sources + per-source token presence (redacted)

License

Apache-2.0 © Neuralchowder Inc. — xema.dev. @xemahq/xema is the open developer/operator tool tier (like the Xema SDKs), distributed under the Apache License 2.0. See LICENSE / NOTICE.