mluctl command reference
Software 3.4 · commands stable across the 3.x line · reviewed 2026-08-22
Every command is mluctl <group> <verb> [target] [options].
Groups do nothing on their own; mluctl device with no verb prints the verbs it
knows. A target is an address, a serial number or a device label, and all three are accepted anywhere
one of them is.
Two global options are worth knowing before anything else:
| --json | Machine-readable output for every command that prints a table. Stable format. |
|---|
| --dry-run | Accepted by every command that changes something. Prints what would happen and exits 0. |
|---|
status, net, log
| Command | Does |
|---|
| mluctl status | One screen: version, uptime, device count, last pass, queue depth, disk, NTP offset. The first thing to run, always. |
| mluctl net show | Interfaces, addresses, routes, DNS, and whether the LAN gateway answers. |
| mluctl net test <host> | Resolution, reachability and SNMP response from the unit’s own point of view. |
| mluctl log tail [--service <name>] | Live log. Services: collect, queue, console, alert. |
| mluctl log grep <pattern> --since 24h | Search the stored log. |
mluctl status
mluctl net test 10.20.4.31
mluctl log tail --service collect
device, scan
| Command | Does |
|---|
| device list [--unreachable] [--profile generic] | Inventory, filtered. |
| device show <target> | Everything known about one device. |
| device add <address> --credential <name> | A device outside every scan range. |
| device label <target> --location <text> | Set location and display name. |
| device profile <target> --set <profile> | Override profile matching. |
| device exclude <address> --reason <text> | Keep it out of reports and alerts. |
| device forget <target> | Remove the record. History is kept and reattaches if the serial reappears. |
| scan range add|list|remove | Manage scan ranges. |
| scan run [--range <label>] | Discovery now. slows collection while it runs. |
# everything that has not answered since yesterday
mluctl device list --unreachable --json
# adopt one printer on a subnet we do not scan
mluctl device add 10.60.2.9 --credential branch-v3 --label "Branch North reception"
meter, supply, export
| Command | Does |
|---|
| meter read <target>|--all [--verbose] | Read now, outside the schedule. |
| meter history <target> --last 30d [--flags] | Stored readings with gap, reset and implausible markers. |
| meter schedule show|set | Interval and closing time. |
| meter accept-reset <target> --at <date> --note <text> | Annotate a counter reset after checking the service record. |
| supply show <target> | Levels, estimates and thresholds for one device. |
| supply due --within 21d | What runs out soon, across the site. |
| supply threshold set ... | Per-model or per-device thresholds. |
| supply hide <target> --class <class> | Suppress a supply the device does not really have. |
| export meters --from --to --format | One-off export. |
| export schedule add|list|remove | Recurring exports by mail or to a share. |
mluctl meter read --all --verbose
mluctl meter history HQ-2-COLOUR --last 90d --flags
mluctl export meters --from 2026-08-01 --to 2026-08-31 --format csv --out /var/spool/mlu/aug.csv
queue, release
| Command | Does |
|---|
| queue list [--user <login>] [--older 12h] | Held jobs: id, owner, size, pages, age. Never contents. |
| queue show <job-id> | What the job needs: language, colour, size, finishing. |
| queue move <job-id> --pool <pool> | Make it releasable elsewhere. Refused if the pool cannot do the job. |
| queue cancel <job-id> | Delete one job. Logged with the operator name. |
| queue purge --older 72h | Housekeeping. irreversible |
| release enable|disable | Turn the feature on or off. disruptive |
| release drain | Stop accepting new jobs, keep the held ones releasable. Use before maintenance. |
| release pool add|list|remove | Group the devices a job may be released on. |
| release limits show|set | Hold time, job size, queue size, jobs per user. |
backup, update, service
| Command | Does |
|---|
| backup create [--to usb|<path>] | Configuration, devices, thresholds, users. Not held jobs, not raw meter history older than 90 days. |
| backup restore <file> | Replaces the current configuration. disruptive |
| backup schedule set --weekly sun --to <path> | Recurring copy to a share. |
| update check | Ask the update host what is available. Needs outbound 443. |
| update apply [--file <ipk>] | Install, from the network or from USB. disruptive, 3–6 minutes. |
| update rollback | Return to the previous release. One step only. |
| service restart <name> | Restart one service without rebooting. |
| diag bundle [--out <path>] | Collect logs, configuration and a self-test into one file for the documentation desk. |
| reboot | What it says. Held jobs survive; a job printing at that moment does not. |
# the four minutes before any maintenance window
mluctl backup create --to usb
mluctl release drain
mluctl status
Exit codes
| Code | Meaning |
|---|
| 0 | Success, including --dry-run. |
| 1 | General failure. The message says which. |
| 2 | Wrong usage: unknown verb, missing argument. |
| 3 | Target not found — no such device, job or profile. |
| 4 | Device unreachable or SNMP refused. |
| 5 | Refused by policy: the pool cannot do the job, the value is out of range. |
| 6 | Busy — a scan, update or restore is already running. |
| 7 | Insufficient rights for this account. |
Scripts should test for 4 and 6 separately and
retry those; everything else is a real error and retrying it just fills the log.