hivecast invoke

Note on naming: the original docs portal TOC entry is "hivecast actor invoke", but the actual command in hivecast.mjs:446 is bare hivecast invoke with no actor segment. There is no hivecast actor namespace in the wrapper.

Synopsis

hivecast invoke <mount> <op> [json]

Sends an actor request through the local Host's NATS transport. Equivalent to the host-service CLI's invoke command — the wrapper just forwards arguments via the delegation list (hivecast.mjs:425).

Argument	Meaning
<mount>	The actor mount to call, e.g. system.devices, chat.conversation, director.http
<op>	The op name, e.g. devices.list, messages.append, routes.list
[json]	Optional JSON-encoded payload, passed as the request body

Examples

List linked Devices on this Host:

hivecast invoke system.devices devices.list '{"includeOffline":true}'

Read the gateway's route inventory:

hivecast invoke system.gateway.http routes.list '{}'

Get host-control state:

hivecast invoke system.runtimes runtimes.list '{}'

Output

The command writes the response envelope to stdout as JSON. The exact shape is determined by the actor and op being called; refer to the owning package's documentation. Errors come back as a structured envelope with a non-zero process exit code.

How it works under the hood

1. Wrapper recognizes invoke is in the delegated list (hivecast.mjs:425).
2. Wrapper spawns the host-service CLI as a child process: node <hostServiceCli> invoke <mount> <op> [json] --home <host-home>.
3. Host-service CLI builds a request envelope, publishes it to the local NATS, awaits the reply on the correlation subject, prints the response.
4. Wrapper exits with the child's exit code.

Source: runHostDelegatedCommand at hivecast.mjs:431-480.

Caveats

• Only mounts on the local Host's authority root. hivecast invoke does not currently route to remote Hosts. To call a remote Host's actor, use matrix invoke with explicit --home <other-host-home> or call through the gateway's HTTP path.
• Requires the local Host to be running. If hivecast status shows the Host is down, invoke will fail with a NATS connection error.
• Op name must be exact. There is no fuzzy matching. If unsure, run hivecast invoke <mount> $introspect (every Matrix actor responds to $introspect with its op list and schemas, per the Actor Communication Contract — see WORKSTREAMS/core-and-packaging/ACTOR-COMMUNICATION-CONTRACT.md).

Target state

A grouped hivecast actor invoke (and adjacent hivecast actor list, hivecast actor introspect) is a defensible future enhancement. Not in code today.

See also

• hivecast up / down — bring the actor's runtime up before invoking
• hivecast runtimes — list active runtimes (one of which owns the mount you want to invoke)
• Actor Communication Contract: WORKSTREAMS/core-and-packaging/ACTOR-COMMUNICATION-CONTRACT.md — defines the op envelope and the universal $introspect op

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs line 446 (signature) and 425 (delegation); implementation in projects/matrix-3/packages/host-service/src/cli.ts.