> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Broker Commands

> Complete reference for Coreflux MQTT Broker commands

## Overview

The Coreflux MQTT broker provides a rich set of commands that you can use to manage users, rules, models, actions, routes, and more. These commands are published to the `$SYS/Coreflux/Command` topic to control and configure the broker.

## Why Use Broker Commands?

Instead of editing configuration files and restarting the broker, you can manage everything at runtime through MQTT messages. Add users, deploy LoT Actions, configure Routes—all without downtime.

<Tip>
  **Think of broker commands as a remote control for your broker.** You send a message to a special topic, and the broker immediately responds—no SSH, no restarts, no manual file editing.
</Tip>

***

## Command Format

Commands are sent to the broker via MQTT messages published to the `$SYS/Coreflux/Command` topic. The general format is:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-commandName <argument>
```

For example:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION MyAction ON EVERY 10 SECONDS DO PUBLISH TOPIC "test" WITH "hello"
```

<Info>
  Command responses are published to `$SYS/Coreflux/Command/Output`. Subscribe to this topic to receive feedback from your commands.
</Info>

## User Management Commands

Manage broker users and their credentials.

### Adding a User

Create a new user with a username and password:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addUser <username> <password>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addUser operator SecurePass123!
```

<Check>
  Response: `User operator added successfully!`
</Check>

### Removing a User

Remove an existing user from the broker:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeUser <username>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeUser operator
```

<Check>
  Response: `User operator removed successfully!`
</Check>

### Changing User Password

Update a user's password:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-changeUserPassword <username> <newPassword>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-changeUserPassword operator NewSecurePass456!
```

<Check>
  Response: `Password for user operator changed successfully!`
</Check>

### Changing User Settings

Modify specific settings for a user:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-changeUserSettings <username> <settingName> <newValue>
```

<Check>
  Response: `Settings for user updated successfully!`
</Check>

***

## LoT Commands

Commands for managing LoT (Language of Things) entities.

### Rules

Rules define access control and permissions for the broker. See the [Rules documentation](/v2.0/lot-language/rules/overview) for complete syntax reference.

<Note>
  Rules are LoT code and can also be deployed directly from a [LoT Notebook](/v2.0/quick-start/vscode) by running the cell containing your rule definition.
</Note>

#### Adding a Rule

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addRule DEFINE RULE <RuleName> WITH PRIORITY <number> FOR <Scope> [TO TOPIC "<pattern>"]
    IF <condition> THEN
        ALLOW
    ELSE
        DENY
```

**Example — Restrict Action creation to admins:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addRule DEFINE RULE AllowActionCreation WITH PRIORITY 1 FOR ActionManagementCreation
    IF USER IS "root" OR USER IS "admin" THEN
        ALLOW
    ELSE
        DENY
```

<Check>
  Response: `Rule 'AllowActionCreation' added successfully`
</Check>

**Example — Control topic access:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addRule DEFINE RULE RestrictSensorPublish WITH PRIORITY 1 FOR Publish TO TOPIC "sensors/#"
    IF USER HAS SensorPermission THEN
        ALLOW
    ELSE
        DENY
```

<Check>
  Response: `Rule 'RestrictSensorPublish' added successfully`
</Check>

#### Removing a Rule

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeRule <ruleName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeRule AllowActionCreation
```

<Check>
  Response: `Rule 'AllowActionCreation' removed successfully`
</Check>

***

### Models

Models define data structures for topic payloads.

#### Adding a Model

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addModel DEFINE MODEL <modelName>
    <model definition>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-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
```

<Check>
  Response: `Model 'TemperatureSensor' added successfully`
</Check>

#### Removing a Model

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeModel <modelName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeModel TemperatureSensor
```

<Check>
  Response: `Model 'TemperatureSensor' removed successfully`
</Check>

#### Removing All Models

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAllModels
```

<Check>
  Response: `All models removed successfully`
</Check>

<Warning>
  This command removes ALL models from the broker. Use with caution.
</Warning>

***

### Actions

Actions define automated behaviors triggered by events or schedules.

#### Adding an Action

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION <actionName>
    <action definition>
```

**Example - Time-based Action:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION Heartbeat
    ON EVERY 10 SECONDS DO
        PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

**Example - Topic-based Action:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION EchoMessage
    ON TOPIC "input/data" DO
        PUBLISH TOPIC "output/echo" WITH PAYLOAD
```

<Check>
  Response: `Action 'Heartbeat' added successfully`
</Check>

#### Removing an Action

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAction <actionName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAction Heartbeat
```

<Check>
  Response: `Action 'Heartbeat' removed successfully`
</Check>

#### Running an Action Manually

Trigger an action to run immediately:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-runAction <actionName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-runAction Heartbeat
```

<Check>
  Response: `Action 'Heartbeat' executed successfully`
</Check>

#### Removing All Actions

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAllActions
```

<Check>
  Response: `All actions removed successfully`
</Check>

***

### Routes

Routes configure connections to external systems and data pipelines.

#### Adding a Route

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addRoute DEFINE ROUTE <routeName> WITH TYPE <routeType>
    <route configuration>
```

**Example - MQTT Bridge:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-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"
```

<Check>
  Response: `Route 'CloudBridge' added successfully`
</Check>

#### Removing a Route

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeRoute <routeName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeRoute CloudBridge
```

<Check>
  Response: `Route 'CloudBridge' removed successfully`
</Check>

#### Listing All Routes

Get a list of all registered routes:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-listRoutes
```

<Check>
  Response: List of all registered routes with their status
</Check>

#### Getting Route Template Code

Retrieve a template for a specific route type:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-routeCode <routeType>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-routeCode POSTGRESQL
```

<Check>
  Response: Template code with all available parameters for the route type
</Check>

#### Removing All Routes

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAllRoutes
```

<Check>
  Response: `All routes removed successfully`
</Check>

***

### Diagnostics

Commands for troubleshooting and debugging LoT entities.

#### Running LoT Diagnostic

Run diagnostics on a specific entity:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-lotDiagnostic <entityType> <entityName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-lotDiagnostic action MyAction
```

<Check>
  Response: Diagnostic information for the specified entity
</Check>

#### Getting Pending Status

Check the status of pending models and actions:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-getPendingStatus
```

<Check>
  Response: Status of all pending models and actions
</Check>

***

## Environment & Secrets Commands

<Info>
  **Version Requirement:** Environment variable and secret commands are available from **Coreflux Broker v1.9.3** and above.
</Info>

Manage environment variables and encrypted secrets at runtime. Environment variables are stored in plain text in the `.env` file. Secrets are encrypted with AES-256-GCM and stored in `secrets.json`. See [Environment Variables & Secrets](/v2.0/mqtt-broker/secrets-and-env) for full details.

### Setting an Environment Variable

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-setEnv NAME=value
```

Persists the variable to the managed `.env` file.

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-setEnv DB_HOST=postgres.example.com
```

<Check>
  Response: `Environment variable 'DB_HOST' set successfully`
</Check>

### Removing an Environment Variable

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeEnv NAME
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeEnv OLD_CONFIG
```

<Check>
  Response: `Environment variable 'OLD_CONFIG' removed successfully`
</Check>

### Listing Environment Variables

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-listEnv
```

<Check>
  Response: List of all managed environment variables and their values
</Check>

***

### Setting a Secret

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-setSecret NAME=value
```

Encrypts the value with AES-256-GCM and persists it to `secrets.json`.

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-setSecret DB_PASSWORD=my_secure_password
```

<Check>
  Response: `Secret 'DB_PASSWORD' set successfully`
</Check>

### Removing a Secret

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeSecret NAME
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeSecret OLD_API_KEY
```

<Check>
  Response: `Secret 'OLD_API_KEY' removed successfully`
</Check>

### Listing Secrets

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-listSecrets
```

<Check>
  Response: List of secret names (values are never displayed)
</Check>

<Warning>
  Secret values are never shown in command output, logs, or any broker interface. Only secret names are listed.
</Warning>

***

## Python Integration Commands

Manage Python scripts within the broker for custom data processing.

### Adding a Python Script

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addPython <scriptName> <code>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addPython Calculator
# Script Name: Calculator

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

def multiply(a, b):
    return a * b
```

<Check>
  Response: `Python script 'Calculator' added successfully`
</Check>

<Note>
  Python scripts must start with `# Script Name: YourScriptName` to be recognized by the system. The script name is used when calling Python functions from LoT actions using the `CALL PYTHON` syntax.
</Note>

### Removing a Python Script

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removePython <scriptName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removePython Calculator
```

<Check>
  Response: `Python script 'Calculator' removed successfully`
</Check>

### Installing Python Packages

Install additional Python packages via pip:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-installPythonPackage <packageName>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-installPythonPackage numpy
```

<Check>
  Response: `Package 'numpy' installed successfully`
</Check>

### Listing Installed Packages

View all installed Python packages:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-listPythonPackages
```

<Check>
  Response: List of all installed Python packages
</Check>

### Removing All Python Scripts

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAllPythonScripts
```

<Check>
  Response: `All Python scripts removed successfully`
</Check>

***

## System Commands

### Trace Logging Commands

Trace logging allows you to capture and monitor specific log events in the Coreflux system.

#### Adding a Trace Log Point

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addTraceLog level=<Level>,lifetime=<Seconds>,messageContains=<Substring>,topic=<mqttTopic>
```

**Parameters:**

| Parameter         | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `level`           | Log level: `Debug`, `Information`, `Warning`, `Error`, `Fatal` |
| `lifetime`        | Duration in seconds before the trace point expires             |
| `messageContains` | Filter logs containing this substring                          |
| `topic`           | MQTT topic where matching logs will be published               |

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-addTraceLog level=Information,lifetime=3600,messageContains=sensor,topic=logs/sensors
```

This creates a trace point that:

* Captures logs at Information level or higher
* Automatically expires after 3600 seconds (1 hour)
* Only captures logs containing "sensor"
* Publishes matching logs to `logs/sensors`

<Check>
  Response: `Trace log point added successfully`
</Check>

#### Listing Trace Log Points

View all active trace points:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-listTraceLogs
```

<Check>
  Response: List of all active trace log points
</Check>

#### Removing a Trace Log Point

Remove a specific trace point by topic:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeTraceLog <topic>
```

**Example:**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeTraceLog logs/sensors
```

<Check>
  Response: `Trace log point removed successfully`
</Check>

#### Removing All Trace Log Points

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-removeAllTraceLogs
```

<Check>
  Response: `All trace log points removed successfully`
</Check>

***

### Connection Status

View the status of all database connections and their recovery patterns:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-connectionStatus
```

<Check>
  Response: Status of all database connections
</Check>

### Update Data

Trigger a refresh of broker data:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
-updateData
```

<Check>
  Response: `Data refresh triggered successfully`
</Check>

***

## Command Authorization

Commands are subject to authorization rules defined in the broker. Not all users may have permission to execute all commands. See the [Rules documentation](/v2.0/lot-language/rules/overview) for information on setting up access control.

<Warning>
  Always ensure proper access control is configured before exposing the command topic to untrusted clients.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="LoT Actions" icon="bolt" href="/v2.0/lot-language/actions/overview">
    Learn how to create automated behaviors
  </Card>

  <Card title="LoT Models" icon="database" href="/v2.0/lot-language/models/overview">
    Structure and transform your MQTT data
  </Card>
</CardGroup>