hivecast login / connect / whoami / logout / link-status

These five commands form the Device Link ceremony — the pairing flow between this local Host (a Device, in product language) and a HiveCast cloud account.

The dispatcher is a single recognizer at hivecast.mjs:413:

return ['login', 'connect', 'logout', 'whoami', 'link-status'].includes(process.argv[2] ?? '');

…all five are routed through runHiveCastLinkCommand (hivecast.mjs:1770-1774).

hivecast login

hivecast login [--setup-code <code>] [--cloud <url>] [--route-key <key>]

Pairs this Device to a HiveCast account interactively. Opens a browser for OAuth (or accepts a setup-code from the cloud's Devices page) and persists the resulting link record into <host-home>/credentials/hivecast-link.json.

Flag	Meaning
--setup-code <code>	Use a setup-code from the cloud Devices page instead of opening a browser
--cloud <url>	Override the cloud endpoint (default https://hivecast.ai). For dev, e.g. http://127.0.0.1:3100 against a sibling Host playing the platform role
--route-key <key>	Pre-claim a public Space-path for this Device

After successful login the Host knows its hostLinkId, principal/Space metadata, per-device credentials, and deviceRegistryRoot. Subsequent heartbeats from host.control carry that link.

Note (terminology): the user-facing product term is Device. Internal storage names — hostLinkId, installId, host.json, configName — are intentionally kept out of UI copy. See WORKSTREAMS/product-launch/CONSTRAINTS.md C27.

hivecast connect

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

A non-interactive variant of login. Used in headless / scripted setups where the cloud URL and device name are known up front. Performs the same pairing flow and writes the same link record.

hivecast whoami

hivecast whoami

Prints the linked principal/account/Space identity for this Device. Reads from <host-home>/credentials/hivecast-link.json plus <host-home>/credentials/hivecast-install.json. If no link is present, prints "not linked" and exits non-zero.

hivecast link-status

hivecast link-status

Inspects the current link's health: cloud reachability, last successful heartbeat, last error if any. More detailed than whoami. Useful in incident response when "did pairing succeed?" is the question.

hivecast logout

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

Tears down the Device Link.

Flag	Behaviour
(default)	Local-only logout. Deletes <host-home>/credentials/hivecast-link.json. The cloud account still considers this Device linked until it observes the heartbeat going stale; explicitly revoking on the cloud side is preferred for security.
--local-only	Same as default — explicit form. Useful in scripts to make intent clear.
--revoke-cloud-link	Calls the cloud's revocation endpoint to mark this Device unlinked on the platform side too.
--all	Like --revoke-cloud-link but also clears hivecast-install.json. The Device's installId is regenerated on the next hivecast install.

Identity files involved

Three files in <host-home>/credentials/ participate in the link ceremony:

File	When created	Survives logout?
hivecast-install.json	First hivecast install (per ensureHiveCastInstallIdentity in mx-cli)	Yes, unless --all
hivecast-link.json	First hivecast login / connect (per generateHostId in system-auth)	Removed on logout
host.json	hivecast install	Yes — local Host config, independent of cloud link

Where it lives in source

• Dispatcher: runHiveCastLinkCommand at hivecast.mjs:1770-1774.
• Auth/grant logic (cloud side): projects/matrix-3/packages/system-auth/src/host-auth.ts — generateHostId, link-grant verification.
• Link-record persistence (Host side): projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts — ensureHiveCastInstallIdentity, link record IO.
• Heartbeat path: host.control reads the link, sends heartbeats to system.devices (locally for owner-mode Hosts, or cloud /_auth/host-link/heartbeat for cloud-linked Hosts).

See also

• Cloud Account → Login
• Cloud Account → Device pairing
• Devices → Pairing (separate docs-devices package)
• Security → OAuth providers (separate docs-security package)

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 413 (recognizer), 447-451 (signatures), 1770-1774 (dispatch); auth/grant in system-auth; link record IO in mx-cli.