@open-matrix/cli (1.1.33)
Installation
@open-matrix:registry=npm install @open-matrix/cli@1.1.33"@open-matrix/cli": "1.1.33"About this package
@open-matrix/cli — matrix, the bus client
matrix talks to live actors on the bus: invoke an operation, watch a subject,
explain how a target resolves. hivecast invoke is the product spelling of
matrix invoke and forwards here.
Prior art: kubectl (talk to the live system), the nats command line,
curl. One of five tools
(governing design §10.1).
Verbs
| Verb | Does | Prior art |
|---|---|---|
matrix invoke <mount> <operation> [payload] |
Sends one operation and prints the reply; payload is inline JSON, @file or @- |
kubectl exec, nats request, curl -X POST |
matrix subscribe <subject> |
Watches a subject and reports message and byte rates | nats sub |
matrix tap <subject> |
Observes a subject without joining its queue group | tcpdump for one subject |
matrix explain <target> |
How a target resolves, which configuration owns it, what it would write | kubectl explain, dig |
matrix broker setup|start|stop |
A local demo broker | nats-server |
Identity comes from --home (a hivecast login home), then ./.matrix, then
~/.matrix, or from the explicit flags below.
Being deleted (design §15): the hidden compatibility commands init,
actor, run, up, package, element, actor-element, cqrs, webapp,
pack, install, uninstall, fork, publish, validate, list, info,
outdated, update-fork, and the identity aliases login, register,
api-keys, whoami, logout. Their verbs belong to hive-pm, hivedock and
hivecast. The examples below that use them describe the commands as they are
until then.
Scope
This package owns the matrix binary.
It does not own managed provider login, machine linking, local platform install, or managed host supervision. Provider overlays can add those flows by writing the broker config shape consumed by the SDK runner.
Common Commands
matrix init
matrix actor greeter
matrix package run . --nats-url nats://127.0.0.1:4222 --root demo --check-op echo
matrix actor run ./dist/GreeterActor.js --mount demo.greeter --nats-url nats://127.0.0.1:4222 --root demo --check-op echo
matrix broker setup
matrix broker start --port 4222
matrix broker stop
matrix config set registry https://registry.npmjs.org/
matrix registry doctor
matrix package run claims the package's mounted inventory in the connected home's
Registry, including when --home selects a HiveCast provider. It uses the existing
profile inventory protocol with volatile leases and the standard foreground heartbeat.
A normal stop (including check mode) releases its own claims before closing the
connection; after a crash or unreachable Registry, leases expire under Registry policy.
A Registry rejection fails startup and cleans up the actor and transport. Direct
standalone brokers with no Registry remain usable; the heartbeat retries discovery.
matrix package run keeps reconnecting through transient broker outages. When
the NATS connection closes terminally (including repeated authorization refusal),
the foreground wait fails and the CLI exits with code 1, even if an actor retains
a heartbeat timer. A supervisor can then relaunch it. SIGTERM closes a disconnected
peer without waiting for the broker to return, including during a stalled WebSocket
upgrade. The local websocket tests exercise this through bin/matrix.mjs with a
temporary broker (nats-server must be on PATH) and HTTP proxy:
pnpm --filter @open-matrix/cli exec node --import tsx --test tests/unit/websocket-peer-lifecycle.spec.ts tests/unit/websocket-handshake-lifecycle.spec.ts
Actor handlers use Matrix handler naming: an accepted op named echo is
implemented as onEcho(payload), not echo(payload). matrix actor run
validates this before connecting to the broker.
Direct runner credentials are resolved from explicit flags, environment
variables, package-local .matrix, and ~/.matrix:
--nats-url / MATRIX_NATS_URL / NATS_URL
--root / --space / MATRIX_ROOT / MATRIX_SPACE
--jwt / MATRIX_NATS_JWT / NATS_JWT
--seed / MATRIX_NATS_SEED / NATS_SEED
./.matrix/credentials/matrix-broker.json
./.matrix/credentials/matrix-nats.json
./.matrix/config.json
~/.matrix/credentials/matrix-broker.json
~/.matrix/credentials/matrix-nats.json
~/.matrix/config.json
JWT and seed must be supplied together. If neither is supplied, the runner connects to the broker without auth, which is intended for local/demo brokers only.
API-key-backed foreground runs renew their exchanged NATS credential from the
JWT's issuer-measured lifetime, without consulting the machine clock. Runs that
share a HiveCast home also share one machine lineage: every start reserves a new
activation generation, and an older still-running activation exits when the
Registry reports that its claims were replaced. A replacement event prompts an
immediate Registry-qualified renewal rather than waiting for the next heartbeat,
and both replacement and stale-generation denials terminate with a
MATRIX_FOREGROUND_ACTIVATION_REPLACED exit reason.
Password registration requires a person's name (displayName in the identity client,
matrix register --display-name in the compatibility CLI). --name still labels the API key.
The name is trimmed, whitespace is collapsed, and at most 120 characters are stored.
Scheduling heard through the bridge on 2026-10-07T13:06:30Z. Scheduling heard through the bridge on 2026-10-07T14:04:02Z.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/federation | 1.1.33 |
| @open-matrix/identity-client | 1.1.33 |
| @open-matrix/package-artifacts | 1.1.33 |
| @open-matrix/package-runtime | 1.1.33 |
| @open-matrix/runtime-control | 1.1.33 |
| commander | ^11.0.0 |
| nats | ^2.29.3 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^25.0.10 |
| esbuild | ^0.27.3 |
| glob | ^13.0.6 |
| tsx | ^4.15.6 |
| typescript | ^5.7.0 |