Broker Commands

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, Routes, 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, Routes, 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

On a cluster, send write commands (add/remove/load) to the leader. Read-only and license commands still run on the node you are connected to.

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

Quick Start

Deploy an Action
List Routes
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.

-listRoutes -requestId routes-1

{
  "success": true,
  "command": "ListRoutes",
  "requestId": "routes-1",
  "message": "Listed 1 route(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." }
  ]
}

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 (-addRoute / --add-route). The table lists the MQTT form you publish.

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`
Routes	`-addRoute`, `-removeRoute`, `-removeAllRoutes`, `-listRoutes`, `-routeCode`, `-checkRouteConnection`, `-routeCertificates`, `-listTemplates`, `-connectionStatus`, `-discoverAIProviders`
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`
License	`-showInstanceKey`, `-loadLicense`, `-installLicense`
Audit	`-auditStatus`, `-auditQuery`, `-auditFilter`, `-decryptAudit`, `-auditExport`
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.

-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.

Routes

-addRoute DEFINE ROUTE 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"

-removeRoute CloudBridge
-removeAllRoutes
-listRoutes
-routeCode POSTGRESQL
-listTemplates
-checkRouteConnection CloudBridge
-connectionStatus

-listRoutes places entries in data (name, type, connection, health). Unmonitored routes report "Unknown" for connection and health. -checkRouteConnection tests the named Route. Details such as routeType and connectionTime are in data. What “connected” means depends on the Route type — see the Route page (for example OPC UA Client or Modbus TCP Server). -routeCode returns template LoT for that Route type in data. -listTemplates lists available templates. -routeCertificates manages PKI for Routes 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.

-routeCertificates 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, MISTRAL_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

Diagnostics

-lotDiagnostic action Heartbeat
-getPendingStatus

-lotDiagnostic takes an entity kind (model, action, route, or rule) and the entity name.

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

-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, Routes, 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. -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 Route-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.

License

-showInstanceKey
-loadLicense /path/to/file.license
-installLicense <license-file-contents>

-showInstanceKey returns the instance key in message. -installLicense takes the license file text (the same content you would read from a .license file), which is the usual path from HUB and other UIs.

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.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Using AI with Coreflux

Product Updates

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

Routes

Diagnostics

Environment Variables and Secrets

Python Integration

Panels and Themes

Projects

License

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

​Routes

​Diagnostics

​Environment Variables and Secrets

​Python Integration

​Panels and Themes

​Projects

​License

​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

Routes

Diagnostics

Environment Variables and Secrets

Python Integration

Panels and Themes

Projects

License

Audit

Trace Logging

Command Authorization

Next Steps