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

***

## In This Page

| Section                                                 | Description                                        |
| ------------------------------------------------------- | -------------------------------------------------- |
| [Command Format](#command-format)                       | How to structure commands                          |
| [User Management](#user-management-commands)            | Add, remove, and configure users                   |
| [LoT Commands](#lot-commands)                           | Manage Rules, Models, Actions, and Routes          |
| [Environment & Secrets](#environment--secrets-commands) | Manage environment variables and encrypted secrets |
| [Python Integration](#python-integration-commands)      | Add and manage Python scripts                      |
| [System Commands](#system-commands)                     | Trace logging and diagnostics                      |

***

## Command Format

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

```bash theme={null}
-commandName <argument>
```

For example:

```bash theme={null}
-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 theme={null}
-addUser <username> <password>
```

**Example:**

```bash theme={null}
-addUser operator SecurePass123!
```

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

### Removing a User

Remove an existing user from the broker:

```bash theme={null}
-removeUser <username>
```

**Example:**

```bash theme={null}
-removeUser operator
```

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

### Changing User Password

Update a user's password:

```bash theme={null}
-changeUserPassword <username> <newPassword>
```

**Example:**

```bash theme={null}
-changeUserPassword operator NewSecurePass456!
```

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

### Changing User Settings

Modify specific settings for a user:

```bash theme={null}
-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](/lot-language/rules/overview) for complete syntax reference.

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

#### Adding a Rule

```bash theme={null}
-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 theme={null}
-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 theme={null}
-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 theme={null}
-removeRule <ruleName>
```

**Example:**

```bash theme={null}
-removeRule AllowActionCreation
```

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

***

### Models

Models define data structures for topic payloads.

#### Adding a Model

```bash theme={null}
-addModel DEFINE MODEL <modelName>
    <model definition>
```

**Example:**

```bash theme={null}
-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 theme={null}
-removeModel <modelName>
```

**Example:**

```bash theme={null}
-removeModel TemperatureSensor
```

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

#### Removing All Models

```bash theme={null}
-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 theme={null}
-addAction DEFINE ACTION <actionName>
    <action definition>
```

**Example - Time-based Action:**

```bash theme={null}
-addAction DEFINE ACTION Heartbeat
    ON EVERY 10 SECONDS DO
        PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

**Example - Topic-based Action:**

```bash theme={null}
-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 theme={null}
-removeAction <actionName>
```

**Example:**

```bash theme={null}
-removeAction Heartbeat
```

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

#### Running an Action Manually

Trigger an action to run immediately:

```bash theme={null}
-runAction <actionName>
```

**Example:**

```bash theme={null}
-runAction Heartbeat
```

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

#### Removing All Actions

```bash theme={null}
-removeAllActions
```

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

***

### Routes

Routes configure connections to external systems and data pipelines.

#### Adding a Route

```bash theme={null}
-addRoute DEFINE ROUTE <routeName> WITH TYPE <routeType>
    <route configuration>
```

**Example - MQTT Bridge:**

```bash theme={null}
-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 theme={null}
-removeRoute <routeName>
```

**Example:**

```bash theme={null}
-removeRoute CloudBridge
```

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

#### Listing All Routes

Get a list of all registered routes:

```bash theme={null}
-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 theme={null}
-routeCode <routeType>
```

**Example:**

```bash theme={null}
-routeCode POSTGRESQL
```

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

#### Removing All Routes

```bash theme={null}
-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 theme={null}
-lotDiagnostic <entityType> <entityName>
```

**Example:**

```bash theme={null}
-lotDiagnostic action MyAction
```

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

#### Getting Pending Status

Check the status of pending models and actions:

```bash theme={null}
-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](/mqtt-broker/secrets-and-env) for full details.

### Setting an Environment Variable

```bash theme={null}
-setEnv NAME=value
```

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

**Example:**

```bash theme={null}
-setEnv DB_HOST=postgres.example.com
```

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

### Removing an Environment Variable

```bash theme={null}
-removeEnv NAME
```

**Example:**

```bash theme={null}
-removeEnv OLD_CONFIG
```

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

### Listing Environment Variables

```bash theme={null}
-listEnv
```

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

***

### Setting a Secret

```bash theme={null}
-setSecret NAME=value
```

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

**Example:**

```bash theme={null}
-setSecret DB_PASSWORD=my_secure_password
```

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

### Removing a Secret

```bash theme={null}
-removeSecret NAME
```

**Example:**

```bash theme={null}
-removeSecret OLD_API_KEY
```

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

### Listing Secrets

```bash theme={null}
-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 theme={null}
-addPython <scriptName> <code>
```

**Example:**

```bash theme={null}
-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 theme={null}
-removePython <scriptName>
```

**Example:**

```bash theme={null}
-removePython Calculator
```

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

### Installing Python Packages

Install additional Python packages via pip:

```bash theme={null}
-installPythonPackage <packageName>
```

**Example:**

```bash theme={null}
-installPythonPackage numpy
```

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

### Listing Installed Packages

View all installed Python packages:

```bash theme={null}
-listPythonPackages
```

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

### Removing All Python Scripts

```bash theme={null}
-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 theme={null}
-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 theme={null}
-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 theme={null}
-listTraceLogs
```

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

#### Removing a Trace Log Point

Remove a specific trace point by topic:

```bash theme={null}
-removeTraceLog <topic>
```

**Example:**

```bash theme={null}
-removeTraceLog logs/sensors
```

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

#### Removing All Trace Log Points

```bash theme={null}
-removeAllTraceLogs
```

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

***

### Connection Status

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

```bash theme={null}
-connectionStatus
```

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

### Update Data

Trigger a refresh of broker data:

```bash theme={null}
-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](/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="/lot-language/actions/overview">
    Learn how to create automated behaviors
  </Card>

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