Login

hivecast login --device is the headless Device pairing command. It runs the device-code flow: the Host requests a deviceCode and a short userCode, the user approves the pairing in any authenticated browser session, and the Host redeems the code for a Host Link.

Command signature

hivecast login [--setup-code <code>] [--cloud <url>] [--route-key <key>] \
               [--device-name <label>] [--home <host-home>]

Flag	Effect
--device	Use the headless device-code flow. Without this flag, hivecast login runs the interactive browser-pair variant.
--setup-code <code>	Pre-fill the user-code that will be approved on the cloud Devices page.
--cloud <url>	Cloud endpoint (default https://hivecast.ai). For dev, point at a sibling Host: --cloud http://127.0.0.1:3100.
--route-key <key>	Pre-claim a public Space-path (v1 alias for spacePath).
--device-name <label>	Set hostName (the mutable human Device label). Internally writes to hostName, never displayName.
--home <dir>	Override <host-home>. Default is ~/.matrix or $MATRIX_HOST_HOME.

What runs locally

The dispatch entry is runHiveCastLinkCommand in projects/matrix-3/packages/hivecast/bin/hivecast.mjs:1770-1774. The link ceremony itself lives in mx-cli and uses these primitives from mx-cli/src/utils/hivecast-link-store.ts:

• ensureHiveCastInstallIdentity({ cwd, matrixHome, hostName }) — writes <host-home>/credentials/hivecast-install.json with a stable installId if it does not already exist. Idempotent: re-running login does not regenerate installId.
• saveHiveCastHostLink(options) — after the cloud returns the redeem response, writes:
  • <host-home>/credentials/hivecast-link.json
  • <host-home>/credentials/hivecast-nats.json
  • <host-home>/credentials/hivecast-host-link-token (if a heartbeat token was issued)
  • <host-home>/credentials.json (mirror of NATS creds)
  • <host-home>/host.json (transport block updated to nats: { mode: 'external', url, wsUrl?, credentialsRef })
• updateHiveCastDefaultRuntimePolicies(matrixHome, hostScope) — flips the default-runtime startup policies (SYSTEM, GATEWAY, WEB, EDGE) to the right scope for the new linked host.

What runs cloud-side

On the cloud system.auth actor, in order:

1. auth.device.start — HostDeviceLinkStore.start() creates a pending record with a fresh deviceCode, userCode (ABCD-EFGH), and 30-minute expiresAt. Status is pending.
2. (user authenticates) — typically Google OIDC via auth.google.login → auth.google.callback, producing a session.
3. auth.device.approve — HostDeviceLinkStore.approve() flips the record's status to approved, records approvedByPrincipalId and hostLinkId. The cloud has now created the Host Link via HostLinkStore.create().
4. auth.device.poll — Host polls until the record is approved.
5. auth.device.exchange — HostDeviceLinkStore.exchange() flips status to exchanged. Side-effect: the gateway responds with a DeviceSetupExchangeResponse (see pairing-grant) carrying the heartbeat token, device-scoped NATS credentials, and link metadata.

After step 5, host.control reads the new hivecast-link.json and starts posting heartbeats. The Devices page is now populated.

What hivecast connect does

hivecast connect <cloud-url> [--route-key <key>] [--name <device-name>]

A non-interactive variant of login. The pairing protocol is the same; the expected use case is scripted setup where the cloud URL and hostName are known up front. The command performs the same five-step ceremony and writes the same files.

What hivecast whoami and hivecast link-status print

After a successful pairing, the Host knows the link without having to call the cloud. Both commands read <host-home>/credentials/hivecast-link.json and <host-home>/credentials/hivecast-install.json:

Command	Reads	Prints
hivecast whoami	hivecast-link.json + hivecast-install.json	principalId, hostName, deviceSlug, installId, cloudUrl
hivecast link-status	hivecast-link.json + host.json	linked, cloudUrl, authorityRoot, routeKey, publicNamespace, spaceId, linkedAt, plus health: natsCredentialsPresent, hostConfigLinked

If no link record exists, both print "not linked" and exit non-zero.

What hivecast logout does

hivecast logout [--local-only] [--revoke-cloud-link] [--all]

Flag	Effect
(default) / --local-only	Removes hivecast-link.json and the device-scoped credential files; resets host.json transport back to local-owner via resetHostConfigToLocalOwner(). Cloud row stays active until heartbeats time out.
--revoke-cloud-link	Calls auth.hostLink.revoke cloud-side first, then performs the local cleanup.
--all	Like --revoke-cloud-link plus also deletes hivecast-install.json. The next hivecast install mints a brand-new installId.

The path-only file removal lives in removeHiveCastCredentialFiles() and removeHiveCastHostLink() in mx-cli/src/utils/hivecast-link-store.ts:568-595.

Idempotency

hivecast login is safe to re-run:

• if installId already exists, it is preserved
• if a Host Link is already active for this hostId, the cloud's HostLinkStore.create() revokes it and creates a fresh record with the same deviceSlug (collision-resolved) and the same hostId
• the Device's deviceSlug is preserved across re-pairings of the same hostId, even if hostName changes

Related ops on the bus

These are the underlying system.auth ops (declared in system-auth/src/index.ts:237-309):

auth.hostLink.create / .get / .list / .revoke / .refresh
auth.hostLink.credentials.refresh
auth.hostLink.verifyHeartbeat
auth.device.start / .status / .approve / .poll / .exchange / .cancel
auth.pair.start / .status / .approve / .exchange / .cancel

Pairing exercises auth.device.* (or auth.pair.*) and produces a row that later ops consume.

See also

• Device flow — protocol-level detail of the device-code flow.
• Host link — the durable cloud-side record this command produces.
• Pairing grant — wire shape of the redeem response.
• Operations / Pair — runbook with command output.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs:1770-1774 (dispatch); projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts (ensureHiveCastInstallIdentity, saveHiveCastHostLink, removeHiveCastHostLink); projects/matrix-3/packages/system-auth/src/host-auth.ts (HostDeviceLinkStore, HostLinkStore).