Skip to content

cli.md

Latest commit

 

History

History
205 lines (145 loc) · 5.49 KB

cli.md

File metadata and controls

205 lines (145 loc) · 5.49 KB
Raw

CLI Reference

The hivemind-client command provides utilities for managing identity and sending test messages.

hivemind-client [--app NAME] [COMMAND] [OPTIONS]

--app NAME makes every command use the identity of that application, ~/.config/hivemind/NAME/_identity.json, instead of the shared ~/.config/hivemind/_identity.json. It goes before the command:

hivemind-client --app voice-sat set-identity --key KEY --password PASS

On a box that only has the shared file, --app NAME uses the shared file and logs a warning until the application has a file of its own. set-identity and reset-pgp with --app NAME always write ~/.config/hivemind/NAME/_identity.json: they give the application its own identity and never touch the shared one. A pin change (forget-server, and the first connection to a hub) lands in the file the application reads. Under the fallback that is the shared file, so the pin is dropped or added for every application on the box; forget-server prints that.

set-identity

Persist node credentials to the identity file (~/.config/hivemind/_identity.json).

hivemind-client set-identity [OPTIONS]
Option Description
--key TEXT HiveMind access key
--password TEXT HiveMind password
--host TEXT Default hub URL, ws:// or wss://
--port INTEGER Default hub port
--siteid TEXT Location identifier injected into message.context

At least one option is required. Each option changes only its own field: a call without --host keeps the stored hub, and on a fresh identity stores none.

Example:

hivemind-client set-identity \
  --key "42caf3d2405075fb9e7a4e1ff44e4c4f" \
  --password "5ae486f7f1c26bd4645bd052e4af3ea3" \
  --siteid "living-room"

terminal

Interactive text terminal. Type utterances and see spoken responses.

hivemind-client terminal [OPTIONS]
Option Description
--key TEXT HiveMind access key (overrides identity file)
--password TEXT HiveMind password (overrides identity file)
--host TEXT HiveMind host URL
--port INTEGER HiveMind port (default 5678)
--siteid TEXT Location identifier (overrides identity file)

Example:

hivemind-client terminal --host ws://192.168.1.10 --port 5678
> what time is it
It is 3:45 PM.

send-mycroft

Send a single OVOS/Mycroft bus message to the hub.

hivemind-client send-mycroft [OPTIONS]
Option Description
--key TEXT HiveMind access key
--password TEXT HiveMind password
--host TEXT HiveMind host
--port INTEGER HiveMind port (default 5678)
--siteid TEXT Location identifier
--msg TEXT OVOS message type to inject
--payload TEXT OVOS message data as a JSON string

The hub must have the message type in this client's whitelist. If it does not, the hub answers hive.policy.denied. Grant it with hivemind-core allow-msg <msg_type> <node_id>.

Example:

hivemind-client send-mycroft \
  --msg "recognizer_loop:utterance" \
  --payload '{"utterances": ["turn off the lights"]}'

escalate

Send a single OVOS message wrapped in a HiveMessageType.ESCALATE envelope. The message is forwarded upstream through the hub hierarchy. It takes the same options as send-mycroft.

hivemind-client escalate [OPTIONS]

propagate

Send a single OVOS message wrapped in a HiveMessageType.PROPAGATE envelope. The message is forwarded to all peers and upstream hubs. It takes the same options as send-mycroft.

hivemind-client propagate [OPTIONS]

ping

Send a PING flood and print the reachable hive topology as an ASCII tree.

hivemind-client ping [OPTIONS]
Option Description
--key TEXT HiveMind access key
--password TEXT HiveMind password
--host TEXT HiveMind host
--port INTEGER HiveMind port (default 5678)
--siteid TEXT Location identifier
--timeout FLOAT Seconds to collect answering PINGs (default 5.0)
--json Print the raw JSON topology instead of the tree

See the CLI Guide for sample output.

test-identity

Open a connection with the saved identity and report whether the handshake completes.

hivemind-client test-identity

reset-pgp

Generate a new RSA key pair for this node. Peers that trust the old public key must be updated.

hivemind-client reset-pgp

forget-server

Forget the pinned encryption key of a hivemind-core.

The first time this node connects to a master it records the master's static encryption key, and every later connection checks that the key did not change. This protects the connection, but it also stops the node when the master legitimately changes its key — after a reinstall, a new SD card, or a restore from a backup. The log then reports a key mismatch on every attempt.

Forget the old key, then connect again to trust and record the new one.

hivemind-client forget-server --host 192.168.1.10 --port 5678
Option Description
--host Host of the master. Defaults to the master in the identity file.
--port Port of the master. Defaults to the port in the identity file.

Only forget a key you expected to change. If nothing was reinstalled, another machine may be answering at that address.

← Identity & Credentials · Home · CLI Guide →