HiveCast Product

Appearance

hivecast command overview ​

The hivecast binary dispatches to one of three handlers depending on the subcommand:

  1. Direct wrapper command — handled inside hivecast.mjs itself (install, start, stop, seed, doctor, login, connect, logout, whoami, link-status, operator).
  2. Delegated to host-service CLI — passed through to the underlying Host Service process (status, runtimes, up, down, invoke, init).
  3. Unsupported — the wrapper exits 1 with a message pointing at hivecast --help.

Authoritative command list ​

The following block is the exact help text emitted by hivecast --help (hivecast.mjs:432-457):

HiveCast Host commands:
  hivecast install [--no-start] [--root <root>] [--http-port <port|0|auto>]
  hivecast start [--root <root>] [--http-port <port|0|auto>]
  hivecast seed
  hivecast stop
  hivecast status
  hivecast runtimes
  hivecast doctor [--cloud <url>] [--repair] [--json]
  hivecast up <package-or-path>
  hivecast up <package-or-path> --id <runtime-id> --mount <actor-mount>
  hivecast up <package-or-path> --startup auto --restart always
  hivecast down <runtime-id|package|mount>
  hivecast invoke <mount> <op> [json]
  hivecast login [--setup-code <code>] [--cloud <url>] [--route-key <key>]
  hivecast connect <cloud-url> [--route-key <key>] [--name <device-name>]
  hivecast whoami
  hivecast logout [--local-only] [--revoke-cloud-link] [--all]
  hivecast link-status
  hivecast operator <command> [options]

Package commands live under the matrix binary: matrix install, matrix up, matrix down.
Source-checkout operator commands live under: hivecast operator --help

Commands grouped by purpose ​

GroupCommandsWhat they do
Host lifecycleinstall, start, stop, seedbring the local Host into existence and supervise it
Inspectionstatus, runtimes, doctorreport state of the local Host and its runtimes
Package supervisionup, down, invokestart/stop a package as a supervised runtime; call into a mounted actor
Cloud pairinglogin, connect, logout, whoami, link-statuspair this Device to a HiveCast account, inspect or sever the link
Source-checkout (dev)operator, opsrun dev/operator scripts that require the matrix-work-harness checkout (registry parity, bootstrap publishing, deploy refresh)
Internalbootstrap-default-runtimescalled by the systemd ExecStartPost hook; not for direct human use

Where it lives in source ​

  • Wrapper dispatch: hivecast.mjs:1738-1789 — the chained if/else if that routes the command.
  • Help text: hivecast.mjs:432-457 — the canonical signature listing.
  • Delegated-command list: hivecast.mjs:425 — the array ['init', 'status', 'runtimes', 'up', 'down', 'invoke'] decides which commands fall through to host-service.
  • Direct-handler functions: named installHostProduct, startHostProduct, stopHostProduct, bootstrapHostProduct, runHostDoctor, runSeedCommand, runHiveCastLinkCommand, runHiveCastOperatorCommand.

What is NOT yet a hivecast subcommand ​

The following entries appear in the original docs portal TOC but do not map to a real command in the current code:

  • hivecast host — there is no hivecast host subcommand. The host-lifecycle commands are bare verbs: install, start, stop. Target state would be a grouped hivecast host <verb>; not in code today.
  • hivecast package — package authoring commands live under the matrix binary, not hivecast. The wrapper's help text says so explicitly: "Package commands live under the matrix binary: matrix install, matrix up, matrix down."
  • hivecast logs — there is no hivecast logs subcommand. Logs are read with journalctl -u <service> for systemd-managed Hosts or via the per-runtime files under <host-home>/logs/runtimes/.
  • hivecast actor invoke — the actual command is hivecast invoke <mount> <op> [json] (no actor prefix).

These are documented for completeness on their own pages so navigation isn't broken, but each one is marked clearly as not implemented with a pointer to the real command.

See also ​