Broker Commands - Coreflux Documentation

Control the Broker Over MQTT

Instead of editing files and restarting, you publish a command string to a system topic and the broker applies the change immediately: users, LoT entities, Connectors, projects, secrets, and more.

Like a remote control for the broker. You send a message to a reserved topic; the broker answers on a matching output topic. No SSH and no restart.

When to use broker commands

Deploy or remove Actions, Models, Connectors, and Rules without downtime
Run an Action on demand, or inspect what is loaded
Manage users, groups, environment variables, and secrets
Load LoT notebook projects and check their status
Drive the same verbs from Coreflux HUB Command Console or any MQTT client
Mint, list, and revoke MCP Server bearer tokens

On a cluster (beta), send a command that adds, changes, removes, or loads LoT (actions, models, connectors, rules, Python scripts, panels, Things, projects) to any node, once. A follower passes it to the leader, which commits it on a majority of the nodes, and every node applies it. The node that receives the command checks your permission. Other commands, such as users, agents, licenses, and certificates, run only on the node you are connected to. See LoT in a cluster.

Subscribe first, then publish. Replies are always JSON on a single output topic.

Quick Start

Deploy an Action
List Connectors
Correlate replies

Subscribe to $SYS/Coreflux/Command/Output, then publish the command. Use QoS 1 on both the command and the output subscription.

-addAction DEFINE ACTION Heartbeat ON EVERY 10 SECONDS DO PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

The broker replies with a JSON envelope. success is true when the Action was registered:

{
  "success": true,
  "command": "AddAction",
  "message": "Action 'Heartbeat' added successfully.",
  "entityType": "Action",
  "entityName": "Heartbeat",
  "data": {}
}

List commands put the structured result in data. message stays a short human summary. This example sends -listConnectors. The reply’s command field stays ListRoutes, and -listRoutes remains a supported alias.

-listConnectors -requestId connectors-1

{
  "success": true,
  "command": "ListRoutes",
  "requestId": "connectors-1",
  "message": "Listed 1 connector(s).",
  "data": [
    {
      "name": "CloudBridge",
      "type": "MQTT_BRIDGE",
      "connection": "Connected",
      "health": "Green"
    }
  ]
}

Every client shares $SYS/Coreflux/Command/Output. Pass -requestId so you can match the reply to the request you sent.

-listProjects -requestId demo-1

Read requestId on the envelope root. Omit the flag when you only have one command in flight.

How Commands Work

Role	Topic	Notes
Publish commands	`$SYS/Coreflux/Command`	UTF-8 plain string payload (not a JSON wrapper)
Subscribe for replies	`$SYS/Coreflux/Command/Output`	Always this topic — independent of flags in the command

-commandName <arguments...> [-requestId <correlation-id>]

Flag	Required	Purpose
`-requestId`	No	Client correlation id; echoed as `requestId` in the JSON reply. Alias: `--request-id`

Authorization uses the MQTT session username of the publishing client. Do not send -requestUser in the payload.

Replies always go to $SYS/Coreflux/Command/Output. Do not subscribe to $SYS/Coreflux/CommandResponse. Custom reply routing (-bt) and $SYS/Coreflux/Cloud/Command are not supported.

Response Envelope

Every reply on $SYS/Coreflux/Command/Output is one JSON object. List and query payloads live in data. data is always present: {} when there is nothing structured to return, or [] for an empty list.

Field	Type	Description
`success`	boolean	Whether the command itself succeeded
`command`	string	Command name (`AddRoute`, `ListProjects`, …). Unknown verbs keep the raw `-verb` form
`message`	string	Human-readable summary
`entityType`	string?	Entity kind for deploy, remove, and run commands
`entityName`	string?	Entity name when applicable
`requestId`	string?	Echo of `-requestId` when you sent one
`data`	object or array	Structured result. Always present
`errors`	object[]?	Present when `success` is `false`
`warnings`	string[]?	Non-fatal warnings (for example a project load that skipped one entity)

How to parse a reply

Parse the payload as JSON (always a single object).
Read success, command, and optional requestId from the root.
Read structured results from data.
Read human text from message and failures from errors[].

Error objects

Field	Description
`message`	Error text for that entry
`line` / `column`	1-based source location for LoT parse errors
`sourceLines`	Map of line number to source text
`suggestions`	Parser hints when available

Parse failure example:

{
  "success": false,
  "command": "AddAction",
  "message": "Unexpected token 'WITH' at line 4",
  "entityType": "Action",
  "entityName": "BadAction",
  "data": {},
  "errors": [
    {
      "message": "Unexpected token 'WITH' at line 4",
      "line": 4,
      "column": 12,
      "sourceLines": { "4": "DO PUBLISH TOPIC \"x\"" }
    }
  ]
}

Global failures

Permission denied (command accepted at MQTT, then blocked by RBAC):

{
  "success": false,
  "command": "AddRoute",
  "message": "Permission denied: You are not allowed to execute -addRoute.",
  "data": {},
  "errors": [
    { "message": "Permission denied: You are not allowed to execute -addRoute." }
  ]
}

The reply currently names the Route form of the command, even when the client sent -addConnector. Unknown command:

{
  "success": false,
  "command": "-notARealCommand",
  "message": "Unknown command: -notARealCommand",
  "data": {},
  "errors": [{ "message": "Unknown command: -notARealCommand" }]
}

If the session lacks CommandCall, the publish to $SYS/Coreflux/Command can be rejected before any Output message. Handle both MQTT-level denial and JSON success: false. See RBAC with LoT Rules.

Command Index

Most verbs also accept a dashed alias (-addConnector / --add-connector). The table lists the MQTT form you publish. Each Connector command also has a Route spelling (-addConnector and -addRoute run the same command), kept as an alias. See Connector command spellings.

Area	Commands
Users	`-addUser`, `-removeUser`, `-changeUserPassword`, `-changeUserSettings`, `-addUserToGroup`, `-removeUserFromGroup`, `-listUserGroups`
Rules	`-addRule`, `-removeRule`, `-removeAllProjectRules`, `-restoreRules`
Models	`-addModel`, `-removeModel`, `-removeAllModels`
Actions	`-addAction`, `-removeAction`, `-runAction`, `-removeAllActions`, `-actionTrace`, `-disableAction`, `-enableAction`
Connectors	`-addConnector` (`-addRoute`), `-removeConnector` (`-removeRoute`), `-removeAllConnectors` (`-removeAllRoutes`), `-listConnectors` (`-listRoutes`), `-connectorCode` (`-routeCode`), `-checkConnectorConnection` (`-checkRouteConnection`), `-connectorCertificates` (`-routeCertificates`), `-disableConnector` (`-disableRoute`), `-enableConnector` (`-enableRoute`), `-listTemplates`, `-connectionStatus`, `-discoverAIProviders`
Agents	`-addAgent`, `-removeAgent`, `-listAgents`, `-disableAgent`, `-enableAgent`
Things	`-addThing` (`--dryRun`), `-removeThing`, `-listThings`
Diagnostics	`-lotDiagnostic`, `-getPendingStatus`
Python	`-addPython`, `-removePython`, `-installPythonPackage`, `-listPythonPackages`, `-removeAllPythonScripts`
Panels	`-addPanel` (`-addVisu`), `-removePanel`, `-listPanels`, `-panelCode`, `-updateVisuState`, `-addVisuFile`, `-refreshVisu`, `-addTheme`, `-removeTheme`, `-removeAllThemes`, `-listThemes`
Projects	`-addProject`, `-removeProject`, `-loadProject`, `-unloadProject`, `-listProjects`, `-listEntities`, `-getProject`, `-duplicateProject`, `-projectCheckout`, `-projectPull`, `-projectPush`, `-projectStatus`, `-projectManifest`
Env & secrets	`-setEnv`, `-removeEnv`, `-listEnv`, `-setSecret`, `-removeSecret`, `-listSecrets`
MCP tokens	`-createMcpToken`, `-listMcpTokens`, `-revokeMcpToken`
License	`-activateLicense`, `-loadLicense`, `-refreshLicense`, `-enroll`
Audit	`-auditStatus`, `-auditQuery`, `-auditFilter`, `-decryptAudit`, `-auditExport`
Certificates	`-brokerCertificates` (admin only)
System	`-addTraceLog`, `-listTraceLogs`, `-removeTraceLog`, `-removeAllTraceLogs`, `-updateData`, `-h`

-updateData refreshes broker $SYS statistics and does not publish a reply on $SYS/Coreflux/Command/Output.

User Management

Create a user, then assign groups for USER IN GROUP in LoT Rules. Group commands require user-management permission on the authenticated MQTT session. See RBAC with LoT Rules. These commands manage the local user store. An OIDC access token is not a local user: there is no command to create one, and -listUsers does not show token sessions.

-addUser operator SecurePass123!
-removeUser operator
-changeUserPassword operator NewSecurePass456!
-changeUserSettings alice AllowedUserManagement true
-addUserToGroup alice operators
-removeUserFromGroup alice operators
-listUserGroups alice

-listUserGroups returns { username, groups, count } in data. Permission flags for -changeUserSettings include AllowedUserManagement, AllowedSystemConfiguration, and AllowedLogManagement.

Rules

Rules define access control. See Rules Overview, Rules Syntax, and RBAC. Lower priority number wins. -addRule accepts priorities from 100 to 1 000 000 only; custom ACL rules require Growth or Enterprise.

Rules are LoT code and can also be deployed from a LoT Notebook by running the cell that contains the definition.

-addRule DEFINE RULE RestrictSensorPublish WITH PRIORITY 100 FOR Publish TO TOPIC "sensors/#"
    IF USER IN GROUP "operators" THEN
        ALLOW
    ELSE
        DENY

-removeRule RestrictSensorPublish

Locked built-in system rules cannot be removed. Seed catch-alls (AllowPublishTopic / AllowSubscribeTopic / AllowConnect) may be removed to switch that operation toward default-deny — except Connect, where removing AllowConnect without a replacement leaves CONNECT ungated. See RBAC.

-restoreRules puts AllowPublishTopic, AllowSubscribeTopic, and AllowConnect back to their shipped ALLOW definitions. Missing seeds are re-added; overrides of those names are reset; locked built-ins and your other custom rules are left alone. Requires root or AllowedSystemConfiguration. No arguments.

-restoreRules

-removeAllProjectRules removes permission rules owned by the active project. Built-in rules and operator-authored custom rules stay in place.

Models

-addModel DEFINE MODEL TemperatureSensor
    WITH TOPIC "sensors/+/temperature"
    ADD FIELD temperature WITH TYPE Float
    ADD FIELD unit WITH TYPE String
    ADD FIELD timestamp WITH TYPE DateTime

-removeModel TemperatureSensor
-removeAllModels

-removeAllModels removes every Model on the broker.

Actions

-addAction DEFINE ACTION Heartbeat
    ON EVERY 10 SECONDS DO
        PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

-addAction DEFINE ACTION EchoMessage
    ON TOPIC "input/data" DO
        PUBLISH TOPIC "output/echo" WITH PAYLOAD

-removeAction Heartbeat
-removeAllActions

Run an Action on demand

-runAction runs an Action immediately, regardless of its trigger.

-runAction Heartbeat

Success means the command dispatched the Action. For this form, a failure inside the Action body is not in the command reply — watch $SYS/Coreflux/Actions/<name>/Trace (if tracing is on) or $SYS/Coreflux/Actions/<name>/Error. data.traceId identifies this execution. Callable Actions (those that declare INPUT) accept a JSON object of parameters:

-runAction SetZoneSetpoint {"zone":"f2-north","target":21.5}

The broker rejects a payload on a non-callable Action, invalid JSON, or a non-object JSON value. Topic-triggered Actions (ON TOPIC / ON CHANGE) accept trigger context instead of INPUT bindings when the JSON object contains a topic key. The Action runs synchronously; data includes status, published, durationMs, error, and traceId. You do not need to arm -actionTrace for this form.

-runAction TemperatureMonitor {"topic":"sensors/zone1/temperature","payload":{"value":72}}

`data.status`	Meaning
`success`	Finished; `published` lists messages it emitted
`error`	The Action threw; `error` has the message. Envelope `success` stays `true` — the command worked
`no_trace_captured`	Ran, but no trace was produced

The topic value must match the Action’s trigger pattern (including wildcards). This topic form does not apply to callables — their JSON object is always INPUT bindings, even if it contains a topic key. See Callable ACTIONs for INPUT / CALL ACTION.

Action tracing

-actionTrace Heartbeat
-actionTrace all
-actionTrace status
-actionTrace off
-actionTrace remove Heartbeat

Traces publish to $SYS/Coreflux/Actions/<name>/Trace. Arming auto-expires; data.expiresUtc tells you when. A { "topic": … } -runAction arms tracing for that one call and disarms afterward, unless a live -actionTrace session was already on.

Agents

Agents are their own LoT entity. -addConnector refuses a DEFINE AGENT block, and -listConnectors does not include agents. See AI Connectors and Agents.

-addAgent DEFINE AGENT Planner
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_lot"
-removeAgent Planner
-listAgents

-addAgent on a name that already exists updates that agent and keeps its conversations. -removeAgent cancels running tasks and forgets session memory. -removeConnector refuses to remove a TYPE LLM connector an agent still uses. -addAgent requires AgentManagementCreation. -removeAgent requires AgentManagementRemove. root, admin, and AllowedSystemConfiguration pass those gates, as they do for connectors.

Connectors

-addConnector DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS true
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "factory1/sensors/#"
        WITH DIRECTION "out"

-removeConnector CloudBridge
-removeAllConnectors
-listConnectors
-connectorCode POSTGRESQL
-listTemplates
-checkConnectorConnection CloudBridge
-connectionStatus

Connector command spellings

Each Route command has a Connector spelling. The Route names (-addRoute, -listRoutes, and the rest) stay as aliases. Both forms run the same command, and the reply’s command field keeps the Route name (AddRoute, ListRoutes, …), so scripts that check it keep working.

Route spelling	Connector spelling	Reply `command`
`-addRoute` / `--add-route`	`-addConnector` / `--add-connector`	`AddRoute`
`-removeRoute` / `--remove-route`	`-removeConnector` / `--remove-connector`	`RemoveRoute`
`-removeAllRoutes` / `--remove-all-routes`	`-removeAllConnectors` / `--remove-all-connectors`	`RemoveAllRoutes`
`-listRoutes` / `--list-routes`	`-listConnectors` / `--list-connectors`	`ListRoutes`
`-routeCode` / `--route-code`	`-connectorCode` / `--connector-code`	`GetRouteTemplate`
`-checkRouteConnection` / `--check-route-connection`	`-checkConnectorConnection` / `--check-connector-connection`	`CheckRouteConnection`
`-routeCertificates` / `--route-certificates`	`-connectorCertificates` / `--connector-certificates`	`RouteCertificates`

-addConnector takes the same body as -addRoute, written with either DEFINE CONNECTOR or DEFINE ROUTE:

-addConnector DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS true
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "factory1/sensors/#"
        WITH DIRECTION "out"

When you start the broker with a Connectors file on the command line, use --lot-connectors <path>. -lotrt and --lot-routes remain supported aliases. -listConnectors places entries in data (name, type, connection, health). Unmonitored connectors report "Unknown" for connection and health. -checkConnectorConnection tests the named Connector. Details such as routeType and connectionTime are in data. What “connected” means depends on the Connector type — see the Connector page (for example OPC UA Client or Modbus TCP Server). -connectorCode returns template LoT for that Connector type, or for a REST API app by its app code, in data. -listTemplates lists available templates. -connectorCertificates manages PKI for Connectors that support certificate stores (OPC UA client and server). The argument is cert64: plus base64 of a minified JSON request (stores, list, inspect, trust, delete, export, import). Operation details are in data. See OPC UA Client — Certificate Management.

-connectorCertificates cert64:<base64-of-json-request>

-discoverAIProviders probes configured LLM providers for reachability and models. API keys and host URLs come from secrets and environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_HOST). An optional JSON object can override those values for the probe. Results are also published retained on $SYS/Coreflux/AI/Providers.

-discoverAIProviders

Disable and Enable

These commands switch an action, connector, or agent off or on without deleting it. Each one redeploys the stored definition with a DISABLE true line added right after the DEFINE line, or removed, through the normal add path. An entity already in the requested state is left alone and the command still succeeds.

Command	Entity	MCP tool
`-disableAction <name>` / `-enableAction <name>`	Action	`disable_action` / `enable_action`
`-disableConnector <name>` / `-enableConnector <name>` (aliases `-disableRoute` / `-enableRoute`)	Connector	`disable_route` / `enable_route`
`-disableAgent <name>` / `-enableAgent <name>`	Agent	`disable_agent` / `enable_agent`

-disableConnector PlantHistorian
-enableConnector PlantHistorian

They need the same permission as adding that entity (ActionManagementCreation, ConnectorManagementCreation, AgentManagementCreation). RouteManagementCreation remains a supported alias of ConnectorManagementCreation. With a live project, the change is written back to its notebook cell. A connector, action, or agent that belongs to a Thing is refused: change the Thing instead. -disableConnector refuses a TYPE LLM connector that agents still use. What a disabled entity does: Actions, Connectors, Agents.

Things

-addThing --dryRun DEFINE THING TEMPLATE TankLevel …
-addThing DEFINE THING TEMPLATE TankLevel … DEFINE THING TankFarm …
-listThings
-removeThing TankFarm

Command	What it does	Permission
`-addThing [--dryRun] <DEFINE THING …>`	Deploys every Thing in the payload as one unit. `--dryRun` returns the plan and each child’s expanded code, and changes nothing. `data` holds `things`, `affectedRoots`, and the per-root `plan`	`ThingManagementCreation`
`-removeThing <name>`	Removes a root and its children in reverse order, or an unused template. A template still in use is refused	`ThingManagementRemove`
`-listThings`	Lists every Thing in `data`: `name`, `kind`, `template`, `uses`, `usedBy`, `childCount`, `project`	`CommandCall`

The children a Thing creates are read-only: -addAction, -removeConnector, and the other per-entity commands refuse them and name the owning Thing. -removeAllActions, -removeAllModels, and -removeAllConnectors skip them. See LoT THING.

Diagnostics

-lotDiagnostic true
-lotDiagnostic false
-getPendingStatus

-lotDiagnostic turns global LoT diagnostic tracing on or off. The only argument is true or false. Anything else returns Invalid diagnostic value.

Environment Variables and Secrets

See Environment Variables & Secrets for storage, substitution in LoT, and security notes.

-setEnv DB_HOST=postgres.example.com
-removeEnv OLD_CONFIG
-listEnv
-setSecret DB_PASSWORD=my_secure_password
-removeSecret OLD_API_KEY
-listSecrets

Quote values that contain //, a space, or #. The command is cleaned before it runs. Outside double quotes, //, /* and -- start a comment and cut off the rest of the line, and a space ends the value. Wrap the value in double quotes: -setEnv API_URL="https://api.example.com/v1". The quotes are removed before the value is stored. The same rule applies to -setSecret.

-listEnv returns name/value pairs in data. -listSecrets returns names only — secret values never appear in command output.

Python Integration

-addPython Calculator
# Script Name: Calculator

def add(a, b):
    return a + b

Python scripts must start with # Script Name: YourScriptName. That name is what you pass to CALL PYTHON from a LoT Action.

-removePython Calculator
-installPythonPackage numpy
-listPythonPackages
-removeAllPythonScripts

Panels and Themes

Deploy dashboards written as DEFINE PANEL. -addPanel and -addVisu are the same command. See Defining Panels.

-addPanel DEFINE PANEL LineOverview
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line Overview"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "Temperature" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        BIND VALUE TO TOPIC "sensor/temperature"

-removePanel LineOverview
-listPanels
-panelCode LineOverview
-updateVisuState LineOverview PUBLISHED
-refreshVisu

-updateVisuState takes DRAFT, PUBLISHED, or ARCHIVED. -addVisuFile lot64:<base64> deploys every DEFINE PANEL block from a .lot file encoded as base64. Theme commands: -addTheme (full DEFINE THEME body), -removeTheme, -listThemes, -removeAllThemes. -listPanels and -listThemes also publish catalog data on $SYS/Coreflux/VoT/Panels/ and $SYS/Coreflux/VoT/Themes/.

Projects

A project is a folder of .lotnb files under the broker data path. See Project organization.

-loadProject and -unloadProject remove only entities the broker attributes to that project. Actions, Models, Connectors, Python scripts, and panels you added with -addAction (and similar) while no project was active stay running.

-listProjects
-addProject "https://git.example.com/factory-iot.git" main
-addProject zip64:<base64>
-loadProject factory-iot
-unloadProject
-removeProject factory-iot
-listEntities
-getProject factory-iot
-duplicateProject factory-iot factory-iot-copy
-projectCheckout factory-iot main
-projectPull factory-iot
-projectPush factory-iot
-projectStatus factory-iot
-projectManifest factory-iot

Names may contain spaces or hyphens (-loadProject Traceability System or -loadProject "Traceability System"). / is not allowed. Quote a git URL so the address stays one argument. The branch name is the next argument: -addProject "https://git.example.com/factory-iot.git" main. -listProjects returns name, active, git metadata, and related fields in data. -loadProject returns { project, entities, counts } in data. counts.actions lists user-defined Actions only (not Connector-internal event Actions). Built-in permission rules are omitted. Per-entity failures appear in warnings[]; success can still be true when the load finished with partial errors. The last loaded project is remembered across restarts unless you pass --project at startup. See Startup Options. -unloadProject tears down owned runtime entities and returns the broker to standalone mode. The folder stays on disk. -removeProject also deletes the folder. -getProject exports a zip (base64) on $SYS/Coreflux/Projects/<name>/download. -projectManifest returns hashes of stored files and declared entities so clients can compare a working copy without downloading the zip. The same JSON is published retained on $SYS/Coreflux/Projects/{name}/manifest.

MCP Tokens

Bearer tokens for the MCP Server. These verbs are operator-only (McpTokenManagement) and are not advertised as MCP tools.

-createMcpToken operator cursor-local
-listMcpTokens
-listMcpTokens operator
-revokeMcpToken cursor-local

-createMcpToken <username> <token-name> [ttlDays] returns the plaintext once in data.token. The username must already exist; tool calls run as that user. Token names cannot contain whitespace. -listMcpTokens returns metadata in data.tokens — never the secret. MQTT replies always land on $SYS/Coreflux/Command/Output. That topic’s default audience is wider than McpTokenManagement. Prefer the broker console or the HUB MCP tab when you need the plaintext off that lane.

License

Licenses are signed tokens. Register at portal.coreflux.org for a license — including a 30-day Growth-type trial — and manage your fleet of brokers there. Full operator guide: Licensing and Enrollment.

-activateLicense CFLX-XXXX-XXXX-XXXX
-loadLicense /path/to/license.jws
-loadLicense eyJhbGciOiJFUzI1NiIsInR5cCI6IkNGTFhMSUMi.….<payload>.<signature>
-refreshLicense
-enroll et_…

Command	What it does
`-activateLicense <code>`	Exchanges a `CFLX-…` activation code for a lease and applies the plan immediately. Requires `SystemConfiguration`. No restart.
`-loadLicense <jws-or-path>`	Verifies a signed license — compact JWS text, or a path on the broker host — and stages `config/license.jws`.
`-refreshLicense`	Forces one online lease refresh instead of waiting for the 24-hour timer. Refused when the broker holds no lease.
`-enroll <et_…>`	Stages a single-use enrollment token. The token is never echoed in the reply; the exchange runs in the background.

-loadLicense treats the argument as the license itself when it has the shape of a compact JWS, and as a filesystem path otherwise. That is how Coreflux HUB installs an offline license without writing a file on the broker host.

{
  "success": true,
  "command": "LoadLicense",
  "message": "Signed license verified and stored at <config>/license.jws",
  "data": {}
}

Broker Certificates

-brokerCertificates manages the broker’s TLS server certificate, its Root CA, and the mTLS client trust store (ClientCertificateSourcePath). It is what HUB Certificates uses. It needs administrator rights (AllowedSystemConfiguration), and it is not exposed to the MCP server or to agents, because requests carry certificate bytes and passphrases. Changes are audit-logged. The argument is cert64: plus base64 of a JSON request with an op and an optional requestId that is echoed back.

-brokerCertificates cert64:<base64-of-json-request>

`op`	Fields	Result
`overview`	—	Trust store settings, server certificate, Root CA, TLS port
`list`	—	Path status, threshold, and every file in the storage path and `revoked/`
`import`	`fileName`, `dataB64`, `password` (PKCS#12)	Stores and trusts the file. Private keys in PKCS#12 or combined PEM uploads are discarded. 10 MB limit
`revoke`	`fileName`	Moves the file to `revoked/`. New connections that present it are rejected immediately
`export`	`fileName`, `revoked` (optional)	`fileName` and `dataB64` of a certificate file. Files with private keys and symbolic links are refused
`setSettings`	`storagePath`, `resetPath`, `expiryThresholdDays`, `clientCertificationValidation`, `checkCertificateChainValidation` (all optional)	Saves the settings and returns the overview. `clientCertificationValidation` fully applies after a restart
`replaceServer`	`fileName`, `dataB64`, `keyB64` (optional), `password` (optional)	Replaces the server certificate with a timestamped `.bak-` copy of the old files. Hot-swapped when TLS is already running, otherwise a restart is needed
`replaceRootCa`	`fileName`, `dataB64`	Replaces the Root CA with a timestamped `.bak-` copy and applies it to chain validation
`exportServer` / `exportRootCa`	—	The public certificate as PEM

{ "op": "revoke", "requestId": "r1", "fileName": "plc-line-a.pem" }

The reply’s message is JSON: requestId, op, success, a human message, and data. Mutating ops also republish $SYS/Coreflux/Certificates/Summary.

Audit

-auditStatus
-auditQuery 2026-08-26
-auditQuery 2026-08-26 -auditFilter operationName=UserLogin
-decryptAudit 2026-08-26

-auditQuery takes a date (YYYY-MM-DD). Add -auditFilter field=value in the same payload to narrow results. -decryptAudit decrypts that day’s log; pair with -auditExport <path> to write JSON to a file. Decryption requires the audit key configured on the broker (COREFLUX_AUDIT_KEY).

Trace Logging

Capture broker log lines and republish matches to an MQTT topic.

-addTraceLog level=Information,lifetime=3600,messageContains=sensor,topic=logs/sensors
-listTraceLogs
-removeTraceLog logs/sensors
-removeAllTraceLogs

Parameter	Description
`level`	`Debug`, `Information`, `Warning`, `Error`, `Fatal`
`lifetime`	Seconds until the trace point expires
`messageContains`	Only logs whose message contains this substring
`topic`	MQTT topic where matching logs are published

Command Authorization

Not every user can run every command. Management gates such as CommandCall and per-entity creation flags are defined in LoT Rules. See Rules overview and RBAC.

Configure access control before any untrusted client can publish to $SYS/Coreflux/Command.

Next Steps

System ($SYS) Topics

Subscribe to command output, entity code, and broker telemetry.

Command Console

Run the same commands from Coreflux HUB without a separate MQTT client.

​Control the Broker Over MQTT

​When to use broker commands

​Quick Start

​How Commands Work

​Response Envelope

​How to parse a reply

​Error objects

​Global failures

​Command Index

​User Management

​Rules

​Models

​Actions

​Run an Action on demand

​Action tracing

​Agents

​Connectors

​Connector command spellings

​Disable and Enable

​Things

​Diagnostics

​Environment Variables and Secrets

​Python Integration

​Panels and Themes

​Projects

​MCP Tokens

​License

​Broker Certificates

​Audit

​Trace Logging

​Command Authorization

​Next Steps

System ($SYS) Topics

Command Console

Control the Broker Over MQTT

When to use broker commands

Quick Start

How Commands Work

Response Envelope

How to parse a reply

Error objects

Global failures

Command Index

User Management

Rules

Models

Actions

Run an Action on demand

Action tracing

Agents

Connectors

Connector command spellings

Disable and Enable

Things

Diagnostics

Environment Variables and Secrets

Python Integration

Panels and Themes

Projects

MCP Tokens

License

Broker Certificates

Audit

Trace Logging

Command Authorization

Next Steps