CLI Reference¶

When you can't quite remember whether it's --node-id or a positional argument (it's positional), this is the page to keep open. Every command and flag across the three HiveMind command-line tools, grouped by the tool that provides them — hivemind-core for the server, hivemind-client for satellites, hivemind-presence for discovery.

In a nutshell

hivemind-core — server-side management: client credentials, permissions, policy, and database.
hivemind-client — satellite-side: identity, terminal, and message injection (escalate, propagate, ping).
hivemind-presence — local-network discovery: announce and scan.
NODE_ID, MSG_TYPE, SKILL_ID, and INTENT_ID are positional arguments; omit NODE_ID to pick a client interactively.

hivemind-core¶

This is the server operator's toolbox — everything you do to run the server and manage who may connect. The full command list first, then each command's flags below it. Two habits cover most of them: add-client mints credentials, and the allow-* / blacklist-* pairs tune what a client may do.

Usage: hivemind-core [OPTIONS] COMMAND [ARGS]...

Commands:
  print-config         Print HiveMind server configuration
  listen               Start accepting satellite connections
  add-client           Add credentials for a new client
  delete-client        Remove credentials for a client
  list-clients         List clients and credentials
  export-clients       Export clients and credentials to a CSV file
  rename-client        Rename a client in the database
  allow-msg            Allow a message type for a client
  blacklist-msg        Deny a message type for a client
  allow-escalate       Allow ESCALATE messages from a client
  blacklist-escalate   Deny ESCALATE messages from a client
  allow-propagate      Allow PROPAGATE messages from a client
  blacklist-propagate  Deny PROPAGATE messages from a client
  allow-skill          Remove a skill from a client's blacklist
  blacklist-skill      Blacklist a skill for a client
  allow-intent         Remove an intent from a client's blacklist
  blacklist-intent     Blacklist an intent for a client
  make-admin           Grant admin flag to a client
  revoke-admin         Revoke admin flag from a client
  set-metadata         Set arbitrary metadata on a client
  migrate-db           Migrate the database to a different backend
  policy               Inspect the policy admission chain
  derive-psk           Derive a Noise pre-shared key for a constrained client
  reset-noise-pin      Clear a client's pinned Noise static key
  allow-broadcast      Grant broadcast capability to a client
  blacklist-broadcast  Revoke broadcast capability from a client

NODE_ID (and MSG_TYPE / SKILL_ID / INTENT_ID) are positional arguments, not options. If you omit NODE_ID, the command prompts interactively with a list of clients.

print-config¶

Usage: hivemind-core print-config

Prints the effective server configuration loaded from ~/.config/hivemind-core/server.json.

listen¶

Usage: hivemind-core listen

listen takes no options — all configuration comes from ~/.config/hivemind-core/server.json. Edit that file (see the Configuration Reference) to change ports, database backend, agent/binary protocols, and the policy chain.

add-client¶

Usage: hivemind-core add-client [OPTIONS]

Options:
  --name TEXT        Friendly name for the client
  --access-key TEXT  Custom access key (generated if omitted)
  --password TEXT    Custom password (generated if omitted)
  --admin BOOLEAN    Grant admin powers to the client (default: false)
  --metadata TEXT    Client metadata as a JSON object
  --allow-weak-password  Skip the password-strength check (not recommended)

The node ID is auto-assigned; there is no --node-id option.

Passing --access-key with a key that already belongs to another client is a hard error — the command refuses to overwrite the existing client's password/admin flag and names the conflicting Node ID and friendly name instead. Use rename-client, allow-msg, or delete-client on the existing client, or omit --access-key to generate a fresh one.

There is no crypto-key. The access key admits the client, and the password derives the v3 Noise PSK (see derive-psk) — the Noise handshake is the sole key exchange. A weak, guessable --password is refused unless you pass --allow-weak-password.

A new client is fail-closed until you allow a message type

A freshly added non-admin client has an empty allowed_types whitelist, which means it is DENIED on every message until you explicitly allow at least one type. add-client prints this same warning. Grant access before the client can do anything, e.g.:

hivemind-core allow-msg recognizer_loop:utterance <NODE_ID>

Admin clients are still subject to the allowed_types whitelist. Admin status only grants elevated capabilities like broadcast; grant the message types an admin client needs the same way you would for any other client.

list-clients¶

Lists all registered clients with their node IDs, names, access keys, and permission summary.

export-clients¶

Usage: hivemind-core export-clients [OPTIONS]

Options:
  --path TEXT  Output CSV file path

delete-client¶

Usage: hivemind-core delete-client [NODE_ID]

Options:
  --yes  Skip the confirmation prompt (for scripting)

NODE_ID is a positional argument; omit it to pick from a prompt. Deleting a client permanently revokes its credentials, so the command confirms interactively unless --yes is passed.

allow-msg / blacklist-msg¶

Usage: hivemind-core allow-msg MSG_TYPE [NODE_ID]
Usage: hivemind-core blacklist-msg MSG_TYPE [NODE_ID]

MSG_TYPE and NODE_ID are positional arguments; omit NODE_ID to pick from a prompt.

allow-escalate / blacklist-escalate¶

Usage: hivemind-core allow-escalate [NODE_ID]
Usage: hivemind-core blacklist-escalate [NODE_ID]

NODE_ID is a positional argument; omit it to pick from a prompt. Toggles whether the client may send ESCALATE messages (the can_escalate flag).

allow-propagate / blacklist-propagate¶

Usage: hivemind-core allow-propagate [NODE_ID]
Usage: hivemind-core blacklist-propagate [NODE_ID]

NODE_ID is a positional argument; omit it to pick from a prompt. Toggles whether the client may send PROPAGATE messages (the can_propagate flag).

rename-client¶

Usage: hivemind-core rename-client [OPTIONS] [NODE_ID]

Options:
  --name TEXT  The new friendly name for the client  [required]

NODE_ID is a positional argument; omit it to pick from a prompt. --name is required — omitting it fails with "Missing option '--name'" rather than leaving the name unchanged.

blacklist-skill / allow-skill¶

Usage: hivemind-core blacklist-skill SKILL_ID [NODE_ID]
Usage: hivemind-core allow-skill SKILL_ID [NODE_ID]

SKILL_ID and NODE_ID are positional arguments. These are OVOS-policy-specific and require OVOSAgentPolicy in the server's policy.chain.

blacklist-intent / allow-intent¶

Usage: hivemind-core blacklist-intent INTENT_ID [NODE_ID]
Usage: hivemind-core allow-intent INTENT_ID [NODE_ID]

INTENT_ID and NODE_ID are positional arguments. These are OVOS-policy-specific and require OVOSAgentPolicy in the server's policy.chain.

make-admin / revoke-admin¶

Usage: hivemind-core make-admin [NODE_ID]
Usage: hivemind-core revoke-admin [NODE_ID]

NODE_ID is a positional argument; omit it to pick from a prompt.

set-metadata¶

Usage: hivemind-core set-metadata [OPTIONS] [NODE_ID]

Options:
  --metadata TEXT  Metadata to merge, as a JSON object
  --key TEXT       Metadata key to set (requires --value)
  --value TEXT     Value for --key (parsed as JSON when possible)
  --unset TEXT     Remove a metadata key

NODE_ID is positional; omit it to pick from a prompt. Pass at least one of --metadata, --key/--value, or --unset. Metadata is read by policy plugins (e.g. OVOSAgentPolicy) to make per-client decisions.

migrate-db¶

Usage: hivemind-core migrate-db [OPTIONS]

Options:
  --from MODULE  Source database backend module (default: hivemind-json-db-plugin)
  --to MODULE    Target database backend module (default: hivemind-sqlite-db-plugin)

--from and --to take full plugin module names (e.g. hivemind-json-db-plugin, hivemind-sqlite-db-plugin, hivemind-redis-db-plugin).

policy¶

Usage: hivemind-core policy COMMAND [ARGS]...

Commands:
  list  Print the loaded policy chain
  test  Dry-run a message through the chain

Usage: hivemind-core policy list
Usage: hivemind-core policy test API_KEY MSG_TYPE

policy list prints the two built-in policies (MessageTypeACLPolicy, then DefaultSessionPolicy), always first and non-removable, followed by the plugins configured in policy.chain. policy test looks up the client by API_KEY and runs a fake message of MSG_TYPE through the full chain, printing the verdict.

derive-psk¶

Usage: hivemind-core derive-psk [OPTIONS]

Options:
  --password TEXT  Password to derive the key from (required)
  --node-id TEXT   This server's node ID, used to salt the derivation (required)

Derives the 32-byte v3 Noise pre-shared key for a constrained or microcontroller client that cannot run the full handshake, from the same password and node ID the client is configured with.

reset-noise-pin¶

Usage: hivemind-core reset-noise-pin [NODE_ID]

Clears the trust-on-first-use pinned Noise static key for one client, so it can re-pair after a reinstall or reflash. NODE_ID is positional; omit it to pick from a prompt.

allow-broadcast / blacklist-broadcast¶

Usage: hivemind-core allow-broadcast [NODE_ID]
Usage: hivemind-core blacklist-broadcast [NODE_ID]

Grants or revokes the can_broadcast flag for a client. Broadcast still requires the client to also be an admin (make-admin) to take effect.

hivemind-client¶

Where hivemind-core runs the server, hivemind-client runs on the satellite side — storing its identity, opening an interactive terminal to the hive, and firing individual messages by hand for testing. The one you'll use constantly is set-identity; the rest are for poking at a live hive.

Usage: hivemind-client [OPTIONS] COMMAND [ARGS]...

Commands:
  set-identity       Write connection credentials to the identity file
  terminal           Interactive CLI: inject utterances and print speech
  test-identity      Test connection using the identity file
  reset-pgp          Recreate the RSA key pair for inter-node communication
  send-mycroft       Send a raw OVOS message to hivemind-core
  escalate           Send an OVOS message wrapped in ESCALATE
  propagate          Send an OVOS message wrapped in PROPAGATE
  ping               Flood-ping the mesh and print the responding topology
  forget-server      Drop the pinned Noise key of a master server

set-identity¶

Usage: hivemind-client set-identity [OPTIONS]

Options:
  --key TEXT       Access key
  --password TEXT  Password
  --host TEXT      Server host (ws:// or wss://)
  --port INTEGER   Server port (default: 5678)
  --siteid TEXT    Site identifier for context routing

Writes ~/.config/hivemind/_identity.json.

test-identity¶

Usage: hivemind-client test-identity [OPTIONS]

Options:
  --timeout FLOAT  Seconds to wait for a connection (default: 30.0)

Connects using the saved identity file and reports success or failure — the quickest way to confirm credentials still work after a server-side change.

forget-server¶

Usage: hivemind-client forget-server [OPTIONS]

Options:
  --host TEXT     Server host
  --port INTEGER  Server port

Drops the pinned Noise static key for a master server. Reinstalling the master or restoring it from a backup gives it a new key, so the satellite stops connecting until its old pin is cleared with this command.

terminal¶

Usage: hivemind-client terminal [OPTIONS]

Options:
  --key TEXT       HiveMind access key (default: from identity file)
  --password TEXT  HiveMind password (default: from identity file)
  --host TEXT      HiveMind host (default: from identity file)
  --port INTEGER   HiveMind port (default: 5678)
  --siteid TEXT    Site identifier

Interactive CLI: type utterances to inject and hivemind-core's speech is printed back.

send-mycroft¶

Usage: hivemind-client send-mycroft [OPTIONS]

Options:
  --msg TEXT       OVOS message type
  --payload TEXT   OVOS message data (JSON string)
  --key TEXT       Access key
  --password TEXT  Password
  --host TEXT      Server host
  --port INTEGER   Port (default: 5678)
  --siteid TEXT    Site identifier

escalate¶

Usage: hivemind-client escalate [OPTIONS]

Options:
  --msg TEXT       OVOS message type to inject
  --payload TEXT   OVOS message data (JSON string)
  --key TEXT       Access key (default: from identity file)
  --password TEXT  Password (default: from identity file)
  --host TEXT      Server host (default: from identity file)
  --port INTEGER   Port (default: 5678)
  --siteid TEXT    Site identifier (default: from identity file)

Wraps the OVOS message built from --msg/--payload in an ESCALATE envelope and emits it. Requires the client to be allowed to send ESCALATE (see hivemind-core allow-escalate).

propagate¶

Usage: hivemind-client propagate [OPTIONS]

Options:
  --msg TEXT       OVOS message type to inject
  --payload TEXT   OVOS message data (JSON string)
  --key TEXT       Access key (default: from identity file)
  --password TEXT  Password (default: from identity file)
  --host TEXT      Server host (default: from identity file)
  --port INTEGER   Port (default: 5678)
  --siteid TEXT    Site identifier (default: from identity file)

Wraps the OVOS message built from --msg/--payload in a PROPAGATE envelope and emits it. Requires the client to be allowed to send PROPAGATE (see hivemind-core allow-propagate).

ping¶

Usage: hivemind-client ping [OPTIONS]

Options:
  --key TEXT       HiveMind access key (default: from identity file)
  --password TEXT  HiveMind password (default: from identity file)
  --host TEXT      HiveMind host (default: from identity file)
  --port INTEGER   HiveMind port (default: 5678)
  --siteid TEXT    Site identifier
  --timeout FLOAT  Seconds to collect responses (default: 5.0)
  --json           Output raw JSON topology

Flood-pings the mesh and prints the peers that respond.

reset-pgp¶

Recreates the private RSA key used for inter-node communication. Despite the name, it generates an RSA key pair.

hivemind-presence¶

Discovery commands from the hivemind-presence package.

Usage: hivemind-presence [OPTIONS] COMMAND [ARGS]...

Commands:
  announce  Advertise this node on the local network
  scan      Scan for HiveMind nodes on the local network

announce¶

Options:
  --port INTEGER       HiveMind port number (default: 5678)
  --name TEXT          Friendly device name (default: HiveMind-Node)
  --service-type TEXT  Service type (default: HiveMind-websocket)
  --zeroconf BOOLEAN   Advertise via mDNS/Zeroconf (default: True)
  --upnp BOOLEAN       Advertise via UPnP (default: False)
  --ssl BOOLEAN        Report SSL support (default: False)

scan¶

Options:
  --zeroconf BOOLEAN   Scan via mDNS/Zeroconf (default: True)
  --upnp BOOLEAN       Scan via UPnP (default: False)
  --service-type TEXT  Service type (default: HiveMind-websocket)

Next: Configuration Reference · Plugin Architecture

Source¶

Validated against the HiveMind source:

hivemind_core/scripts.py — every hivemind-core subcommand, its arguments, and the empty-allowed_types warning
hivemind_bus_client/scripts.py — every hivemind-client subcommand and flag
hivemind_presence/scripts.py — the hivemind-presence announce / scan commands