hivecast-sdk/packages/cli/README.md

# @open-matrix/cli

Package-author CLI for Matrix SDK.

## Scope

This package owns the `matrix` binary for SDK users who build, package, and run
Matrix actors and browser surfaces.

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

```bash
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
```

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`:

```text
--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.