CLI Reference
Every miravo command and flag: factory lifecycle, runtime changes, exports, content inspection, and integrations.
Use the CLI to run a factory, change it while it runs, inspect content, and script integrations from a shell or CI job.
Global options
| Option | Purpose |
|---|---|
-V, --version | Print the version |
--debug | Print stack traces for unexpected failures |
-q, --quiet | Suppress all output except errors |
--plain | Use stable plain-text output, no ANSI styling |
--no-input | Never prompt. Use non-interactive defaults. Has no effect on commands that do not prompt |
-v, --log-level, and --log-format belong to start, the only command with a runtime log stream.
Commands
| Group | Commands |
|---|---|
| Run | start · stop · status · logs |
| Operate a running factory | pause · resume · speed · inject · spawn · remove · load · unload · reset · adapter |
| Content | init · validate · lint · templates · models |
| Integrate | le (Litmus Edge: export, apply, clean up, saved targets) · skill |
| Shell | completion |
Commands that talk to a running factory (status, stop, logs, pause, resume, speed, inject, spawn, remove, load, unload, reset, adapter, le export tags) find it in this order: --admin-url, MIRAVO_ADMIN_URL, then the pointer in MIRAVO_HOME. Both start and start -d write the pointer, so miravo speed 10 needs no --admin-url after either. If none of the three is set, the command fails with No Miravo factory found for MIRAVO_HOME=<path> and a fix. There is no 8080 fallback. MIRAVO_ADMIN_HOST and MIRAVO_ADMIN_PORT only choose where start binds. Clients ignore them.
A MIRAVO_HOME holds one factory. To run a second one, give it its own MIRAVO_HOME and target it with that home or with --admin-url.
miravo completion
Print a static completion script for Bash, Zsh, or Fish. The script completes commands, aliases, options, and fixed option values. It does not scan the filesystem or call Miravo.
mkdir -p ~/.local/share/bash-completion/completions
miravo completion bash > ~/.local/share/bash-completion/completions/miravoFor Zsh, keep ~/.zsh/completions in fpath before compinit:
fpath=(~/.zsh/completions $fpath)Open a new shell after writing the file.
| Argument | Purpose |
|---|---|
shell | bash, zsh, or fish |
Side effects: writes the script to stdout. Your redirection creates the file.
Exit codes: 0 success, 1 unsupported shell.
miravo start
Start a factory from a built-in template, a local template, or a comma-separated template list. Use -t none for an empty boot with no assets.
miravo start -t smart-factoryWith a list, the first template boots the factory and the others load after startup. none cannot be combined with other templates. Without --name or MIRAVO_NAME, Miravo derives a factory name from the template or generates one.
Without --template, Miravo uses the one template in the current directory. Otherwise it uses the only other local template it finds (personal or namespaced), and stops with an error if there are several. With no local template, it asks you to pick a built-in one on a terminal, or uses smart-factory when there is no terminal or you pass --no-input.
| Flag | Purpose |
|---|---|
-t, --template <id|name|path,...> | Boot template, none, or a comma-separated list |
-n, --name <name> | Factory name |
-d, --detach | Run in the background and return to the shell |
--dry-run | Validate config and print the summary without starting |
--no-input | Disable prompts and use non-interactive defaults |
-s, --speed <multiplier> | Time multiplier |
--run-for <duration> | Pause at this simulated time (8h, 7d) |
--no-mqtt | Disable the embedded MQTT broker |
The external broker password has no flag. Set MIRAVO_MQTT_PASSWORD so it stays out of shell history and process listings.
The saved state never keeps the broker username, password, or the credentials, query, and fragment of the broker URL. Pass --mqtt-url, --mqtt-username, and MIRAVO_MQTT_PASSWORD again on every restart, with the same scheme, host, and path. Otherwise the restored MQTT adapter stays disabled and start prints a warning naming what is missing.
Side effects: starts the engine, the admin server, the enabled adapters, and the embedded Console unless --no-ui is set. Both modes write the factory pointer (detached.json) under MIRAVO_HOME and remove it on a clean stop. start refuses to run when a live factory already owns that pointer, and the error says to run miravo stop or use another MIRAVO_HOME. A pointer whose admin URL does not answer is stale, and removed, only when this same host wrote it and its PID is gone; one with a different process id is stale too. A live PID is never declared stale, even if its factory is suspended or stalled: start refuses and says to run miravo stop, or to delete detached.json if that PID is not a Miravo factory. A pointer file that cannot be read (unknown shape, truncated) also refuses start and the runtime verbs, naming the file: stop that factory or delete the file. A matching PID never proves staleness: containers sharing a home are all PID 1. MIRAVO_HOME is a single-host directory (one machine, one PID namespace): do not share it across hosts or containers, and never give two hosts or containers sharing one the same hostname. A pointer written by another host, or one with no recorded host (older version, hand-edited), is never removed, signalled or PID-checked locally: start fails naming the host and detached.json (stop that factory there, or delete the file if it is gone), and miravo stop shuts it down over HTTP only and waits for its admin endpoint to go away, leaving the pointer to its owner. Two simultaneous start commands on one MIRAVO_HOME fail with Miravo startup already in progress; the lock is held until the pointer is written, and its owner renews it every 5 seconds; a lock written by this host and not renewed for 30 seconds is stale and is reclaimed, while a lapsed lock written by another host fails closed. Temp files from a killed start are swept after 30 seconds. A start whose lock was taken over by a newer start, or whose lease had already expired, stops with Miravo startup lock was lost and writes no pointer. The pointer is committed exclusively: a second factory cannot overwrite it. When a saved snapshot is restored, start prints Restored saved state: N assets (from <path>). Start fresh with --fresh. For each saved template whose file changed or is gone, it prints Saved state discarded for template '<id>': ... with the reason. These lines also appear in the -d summary. Every saved template reloads on restart, including templates added later with -t a,b or miravo load; see Persistence.
When a template scopes protocols (protocol_scope), the startup banner, the -d summary, and --dry-run list how many assets each enabled protocol serves, for example OPC UA opc.tcp://127.0.0.1:4840 5 of 11 assets. A protocol that serves every asset shows no note. --dry-run --json adds protocolCoverage ({ "opcua": { "assets": 5, "total": 11 } }, enabled protocols only). Confirm exact tags with miravo adapter inspect <protocol>.
Exit codes: 0 success or dry-run validation, 1 invalid input, flag, or environment value, 2 startup dependency failure, 3 template or model fails validation.
-t accepts a template id, a .miravo.yaml file, or a bundle folder such as -t ./ci-factory. A folder must hold exactly one root .miravo.yaml. Otherwise the error names the files it found. A bare name that matches no built-in or personal template id falls back to ./<name> when that is a bundle folder (explicit ids win; validate, lint, load, le export template and le apply resolve the same way). --opcua-port, --opcua-host, --modbus-port and --modbus-host are ignored with a warning unless that protocol is enabled by --opcua/--modbus or a protocols.opcua/protocols.modbus block. When it is, the flag wins over a port saved in the state file. If a detached start fails, the output has one line with the child's first error, one Fix: line (for a port conflict it names the flag, such as -p/--mqtt-port), a short deduplicated log tail, and the log path.
miravo status
Read live engine health, loaded templates, standalone assets, and asset details from a running factory.
miravo status| Flag | Purpose |
|---|---|
-w, --watch | Poll every second and redraw until interrupted |
--asset <id> | Show detail for one asset |
--json | Machine-readable JSON |
The overview ends with two sections. Templates lists each loaded template with its id, name, asset count, and areas with their lines. Standalone lists assets that belong to no template: spawned from a model, or left after an unload. --json prints { metrics, state, templates[], standalone[] }. templates[] holds the loaded templates (templateId, templateName, assetIds, areas) and standalone[] holds { id, model }. --asset shows the asset's template, or standalone.
--json adds state.lines when the template defines production lines. Each entry has line, stations: [{id, state, good, scrap}], and buffers: [{after, level, capacity}]. Station assets also include production signals in state. Human output prints a station and count table plus buffer fill. See Production lines.
Each adapter line starts with connected or disconnected. That is the server or broker state, not whether anything is reading. The next segment counts clients: 2 sessions (OPC UA), 3 clients, 1,204 reads (Modbus: open TCP connections and read requests answered), 2 clients (embedded MQTT broker). --json carries the same numbers in metrics.adapters[].metrics.clients (active, plus subscriptions, reads, writes where the protocol has them). An external MQTT broker has no clients field.
Side effects: read-only.
Exit codes: 0 success, 1 invalid admin URL, bad local input, unknown --asset, 2 no factory found or transport failure, 3 runtime rejection.
When no factory is found, status prints No Miravo factory found for MIRAVO_HOME=<path>. plus how to start one on stdout, as plain information with no error: prefix, and exits 2 so scripts can branch on it. --json keeps the usual stderr error envelope and exit 2. Nothing is probed on http://127.0.0.1:8080.
When --admin-url or MIRAVO_ADMIN_URL is set but nothing answers there, status exits 2 with cannot reach Miravo at <url> and a fix line. A pointer whose process is gone is removed, and status reports that the saved factory is gone.
miravo stop
Stop the factory for this MIRAVO_HOME, or the one at an explicit admin URL.
miravo stop| Flag | Default | Purpose |
|---|---|---|
--admin-url <url> | URL order above | Override the admin target |
--json | Off | Machine-readable output |
--timeout <seconds> | 10 | Shutdown timeout |
Side effects: stops the target and clears the MIRAVO_HOME pointer when the target matches that factory.
Exit codes: 0 success, 1 local target resolution failure, 2 transport failure, 3 runtime rejection.
miravo logs
Stream runtime events over WebSocket from the factory for this MIRAVO_HOME or an explicit admin URL.
miravo logs| Flag | Default | Purpose |
|---|---|---|
--tail <n> | Unset | Fetch the last n events (1 to 1000) before streaming. Other values are rejected with the allowed range |
--no-follow | Follow | Print history and exit. Without --tail, prints the last 50 events |
--channels <list> | faults,lifecycle,assets,engine,adapters | Comma-separated channels. tick is also available |
--json | Off | Emit NDJSON |
--admin-url <url> | URL order above | Override the admin target |
Side effects: by default holds a streaming connection open until interrupted. --no-follow fetches history, writes it to stdout, and exits. Channel filters apply to history too, so a channel with no matching events in the last n prints nothing. If the server rejects the request, the error shows the server's message and hint.
Exit codes: 0 clean shutdown, 1 local target resolution failure, 2 transport failure.
miravo spawn
Add assets from a model name.
miravo spawn centrifugal-pump| Flag | Default | Purpose |
|---|---|---|
-c, --count <n> | 1 | Number of assets to create |
--id <assetId> | Unset | Exact asset id when count is 1 |
--prefix <prefix> | Model-derived | Generate ids like <prefix>-001 |
--protocols <list> | Enabled adapters | Expose only on mqtt, opcua, and/or modbus |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: creates assets. Running the command again creates more. Use --id for one exact id and --prefix to avoid shared defaults like motor-001.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo remove
Remove one asset by id.
miravo remove pump-003miravo remove pump-003 --yes| Flag | Default | Purpose |
|---|---|---|
-y, --yes | Off | Skip the confirmation prompt |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: deletes the asset. Terminal runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success, 1 bad input or missing confirmation, 2 transport failure, 3 runtime rejection.
miravo pause
Pause the running factory without discarding state.
miravo pause| Flag | Default | Purpose |
|---|---|---|
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: stops tick advancement. Runtime state stays in memory.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo resume
Resume a paused factory.
miravo resume| Flag | Default | Purpose |
|---|---|---|
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: restarts tick advancement.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo speed
Set the time multiplier on a running factory.
miravo speed 10| Flag | Default | Purpose |
|---|---|---|
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: changes speed immediately.
Exit codes: 0 success, 1 invalid multiplier or bad local input, 2 transport failure, 3 runtime rejection.
miravo load
Load one or more templates into a running factory. A template loads once: its id is its identity, and its assets are named <template-id>-<model>-NNN unless an assignment sets id:. The template id is the built-in or personal bundle id. For a file that is the only .miravo.yaml in its folder it is the file name without the extension, and otherwise the slug of the template name.
miravo load -t smart-factoryWithout --template, Miravo looks for one template to load, using the same discovery as start.
| Flag | Purpose |
|---|---|
-t, --template <id|name|path,...> | Template id, name, path, comma-separated list, or - for stdin |
--dry-run | Print the load request without sending it |
-y, --yes | Skip the confirmation prompt |
Side effects: adds the template and its assets. Loading a template that is already loaded fails with Template '<id>' is already loaded. Unload it, or give your bundle a different id. If the other template comes from a different path, the error names both paths: template ids are normalized (anything outside letters, digits, - and _ becomes -), so acme/line-a and acme-line-a collide. Rename one bundle folder or file, or change the template name. Unload it first with miravo unload or from the Console. A template loaded from stdin (-t -) does not survive a restart. Terminal runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success or dry run, 1 bad input or missing template, 2 transport failure, 3 runtime rejection.
miravo unload
Unload one template and remove its assets. The template id is the first column of miravo status. Standalone assets stay.
miravo unload smart-factory| Flag | Default | Purpose |
|---|---|---|
-y, --yes | Off | Skip the confirmation prompt |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: removes the template and every asset it generated. The snapshot is updated, so the template stays unloaded after a restart. An id that is not loaded fails with Template '<id>' is not loaded. Terminal runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success, 1 bad input or missing confirmation, 2 transport failure, 3 runtime rejection.
miravo reset
Remove all assets and loaded templates, and save the empty factory so the next start is empty too. A factory started with --template none is stateless: reset does not touch a saved snapshot of that name.
miravo reset| Flag | Default | Purpose |
|---|---|---|
-y, --yes | Off | Skip the confirmation prompt |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: clears runtime state and saves the empty factory. To delete saved state at the next boot instead, use miravo start --fresh. Terminal runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success, 1 bad input or missing confirmation, 2 transport failure, 3 runtime rejection.
miravo inject
Trigger or clear a fault on a running asset.
miravo inject| Flag | Default | Purpose |
|---|---|---|
--clear | Off | Clear the fault instead of triggering it |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: changes fault state. With no positional arguments, inject opens an interactive picker and needs a terminal. Success messages go to stdout and errors to stderr.
Triggering prints how long the effect lasts and how to clear it, for example Injected cavitation on new-pump-001: lasts 180 s simulated (~18 s at 10x). Clear: miravo inject new-pump-001 cavitation --clear. Faults without duration_s stay active until cleared. --json keeps { success, command, message } and adds data: { fault, durationSeconds, timeMultiplier }. Clearing a fault that is not active (it may have already ended) logs a warning and exits 0, because the desired end state holds. --json still prints success: false with data: { reason: "not_active" }.
Exit codes: 0 success, 1 bad input, no terminal for interactive mode, 2 transport failure, 3 the engine rejected the command (for example an unknown asset or fault).
miravo adapter
Manage runtime protocol adapters.
enable
miravo adapter enable mqtt| Flag | Default | Purpose |
|---|---|---|
<name> | Required | mqtt, opcua, or modbus |
-p, --port <number> | Adapter default | Override the adapter port |
--host <host> | Adapter default | Override the bind host |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
disable
miravo adapter disable opcua| Flag | Default | Purpose |
|---|---|---|
<name> | Required | mqtt, opcua, or modbus |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
inspect
miravo adapter inspect modbus --jsonPrints the tag map for one adapter. JSON output keeps only the requested adapter under each tag's protocols, matching the human output.
| Flag | Default | Purpose |
|---|---|---|
[name] | modbus | Adapter to inspect |
--json | Off | Machine-readable output |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: enable and disable change live adapter state. inspect is read-only.
Exit codes: 0 success, 1 invalid adapter name or bad local input, 2 transport failure, 3 runtime rejection.
miravo init
Create a template bundle folder with one root .miravo.yaml entry file. With --from, copy the entry file from a built-in id, a namespaced template bundle, or an absolute template bundle folder. Built-in forks keep shared model references. Local and namespaced forks also copy sibling .asset.yaml overrides.
miravo init packaging-line| Argument or flag | Purpose |
|---|---|
[name] | Template bundle id and destination folder. Omit to initialize the current folder. |
--from <src> | Copy from <builtin-id>, <namespace>/<env-id>, or /abs/path/to/env-folder. |
--json | Print { id, root, entryPath } as JSON. |
Side effects: writes a template bundle folder. The target must be empty. A non-empty target fails at once, with no prompt, even when stdin is closed. --from copies protocol ports too, so change them before starting to avoid collisions.
Exit codes: 0 success, 1 bad input, missing source, or write conflict.
Destinations: miravo init <name> writes $MIRAVO_HOME/templates/<name>/ (default ~/.miravo/templates/<name>/). miravo init with no name writes into the current directory. On success it prints the absolute path of the entry file and the next commands, miravo validate <name> and miravo start -t <name>.
miravo validate
Validate one template bundle folder. Validation checks the entry schema, the model schemas, template-to-model references, and that each filename matches its model.name. Assignment parameters must reference defined numeric parameters and satisfy the model types and min/max bounds (int needs safe integers). Unknown model names are reported in the same run as schema errors (with a did-you-mean). Errors name the template, asset, parameter, value, allowed range, and assignment path. start rejects templates that fail these checks. Spawn variation is clamped to model bounds. The current schema has no enum constraint for parameters.
miravo validate| Argument or flag | Purpose |
|---|---|
[id] | Template bundle id, namespaced id, or path. A bare name that matches no id falls back to the ./<id> folder. Omit to validate the current folder. |
--json | Machine-readable diagnostics. |
Every schema issue is reported as its own diagnostic, not just the first. Each has a path-qualified message (areas[0].lines[0].assets[2]: unknown key "speed"), the 1-based YAML line of the offending node, and an actionable hint: allowed keys with a "did you mean" for unknown keys, the allowed range for out-of-range numbers, valid values for enums, an example for missing keys, and the closest model name for an unknown model reference. file is relative to the bundle root, so messages carry no absolute path. The table output shows file:line.
{
"file": "packing.miravo.yaml",
"line": 10,
"severity": "error",
"message": "areas[0].lines[0].assets[2]: unknown key \"speed\"",
"hint": "Allowed keys: model, id, count, variation, parameters, inputs, starting_hours, protocol_scope. Remove \"speed\"."
}lint, start and load print the same formatted list when a template or model fails the schema. With --json, lint errors on stderr carry the same entries in error.diagnostics.
Side effects: read-only.
Exit codes: 0 valid, 1 bad input or missing template bundle, 3 validation failed, 4 internal failure.
miravo lint
Run deterministic realism checks against one template bundle folder. lint also reports the validation errors above. Warnings do not fail the command unless you pass --strict, which makes them fail CI.
miravo lint| Argument or flag | Purpose |
|---|---|
[id] | Template bundle id, namespaced id, or path. Omit to lint the current folder. |
--strict | Exit non-zero when warnings are found. |
--json | Machine-readable diagnostics. |
Realism rules
| Rule | Flags | Fix |
|---|---|---|
| Vibration coupling | Rotating assets expose vibration signals without speed, load, or torque signals. | Add a coupled driver such as speed, load, torque, or current, then make vibration respond to it. A vibration member that reads another coupled member counts as coupled. |
| Thermal tau | Temperature members jump too quickly or lack a time constant. | Model thermal lag with a first-order response or another slow generator. Members derived from a lagged member or an input port inherit its inertia. Outdoor and ambient boundaries and *_reference, *_target, *_baseline signals are exempt. Air, exhaust, and flue gas streams accept a tau from 10 s. |
| Timetable MRN overlay | Maintenance or reliability state is driven like a fixed schedule instead of an operating-hours signal. | Drive MRN-style state from operating hours, runtime, load, or lifecycle progression. Setpoints, demand flags, phase codes, and presence flags are deterministic by design and exempt. |
| Observation on read-write | Writable members are modeled as observations. | Keep operator-set values writable and model sensor observations as separate readable members. |
| Lifecycle stage jump | Lifecycle stages skip directly across large wear intervals. | Add intermediate stages or adjust thresholds so wear progression is gradual. |
| Observation scale | Observed values use ranges or noise that are implausible for the unit and process. | Tighten eu_range, units, and noise around the expected process envelope. |
| Fault running guard | Faults can trigger while the asset is stopped even though the failure needs operation. | Add a running, speed, load, current, power, firing, stage, demand, or flow guard to the fault trigger. |
Side effects: read-only. Lint never rewrites files. Fix the model or entry file, then run miravo validate and miravo lint again.
A user bundle is linted for its own files only. The built-in models it references are not reported, but linting a built-in template by id still reports the built-in model files it uses. file is relative to the bundle root, or absolute when outside it. Duplicate diagnostics are collapsed. --json returns { valid, bundleId, source, entryPath, diagnostics: [{ file, line?, severity, message, hint }] }, one diagnostic per schema issue with a path-qualified message, the 1-based YAML line and a hint (allowed keys, range, values or a did-you-mean).
Exit codes: 0 clean, or warnings without --strict, 1 bad input or missing template bundle, 3 errors, or warnings with --strict, 4 internal failure.
miravo templates
List, inspect, or remove template bundles. miravo templates without a subcommand prints help. Subcommands: list, inspect, remove.
miravo templates list
List discoverable template bundles with each bundle's source (builtin, personal, namespace, or cwd) and unique model count.
miravo templates list| Flag | Purpose |
|---|---|
--source <source> | Only templates from this source: builtin, personal, namespace, or cwd |
--json | Machine-readable output, one entry per template |
Side effects: read-only.
Exit codes: 0 success, 1 bad input.
miravo templates inspect
miravo templates inspect water-treatment| Argument or flag | Purpose |
|---|---|
<idNameOrPath> | Template bundle id, name, or path |
--raw | Dump the raw YAML. Cannot be combined with --json |
--json | Machine-readable output |
Side effects: read-only.
Exit codes: 0 success, 1 missing template bundle or bad input.
miravo templates remove
Remove a personal, current-directory, or namespaced template bundle folder by id or path. The command refuses built-in bundles, ids that appear under more than one source, and bundles that a detached factory is running.
miravo templates remove my-env| Flag | Purpose |
|---|---|
--purge-state | Also delete ~/.miravo/state/<env>.json |
-y, --yes | Skip the confirmation prompt |
--json | Machine-readable output |
Side effects: deletes the template bundle folder, and --purge-state also removes its persisted state snapshot. Terminal runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success, 1 missing template bundle, bad input, or missing confirmation, 3 refused (built-in, several sources, or running), 4 internal failure.
miravo models
List, inspect, or add asset models. miravo models without a subcommand prints help. Subcommands: list, inspect, add.
miravo models list
List discoverable asset models with each model's source (builtin, personal, namespace, or cwd).
miravo models list| Flag | Purpose |
|---|---|
--source <source> | Only models from this source: builtin, personal, namespace, or cwd |
--json | Machine-readable output, one entry per model |
Side effects: read-only.
Exit codes: 0 success, 1 bad input.
miravo models inspect
miravo models inspect centrifugal-pump| Argument or flag | Purpose |
|---|---|
<name> | Model name |
--raw | Dump the raw YAML |
--json | Machine-readable output |
Side effects: read-only.
Exit codes: 0 success, 1 missing model or bad local path.
miravo models add
Add one .asset.yaml model file to a template bundle. Without --from, Miravo writes a blank model scaffold. With --from, it copies a shared built-in model, a model from a namespaced template bundle, or an absolute .asset.yaml file.
miravo models add coolant-pump --in packaging-line| Argument or flag | Purpose |
|---|---|
<name> | New local model name. The file is <name>.asset.yaml. |
--in <id> | Target template bundle id. Defaults to the current folder. |
--from <src> | Copy from <builtin-model-id>, <namespace>/<env-id>/<model>, or /abs/path/to/file.asset.yaml. |
--json | Print { model, path, entryPath, registration } as JSON. |
Side effects: writes one sibling .asset.yaml file.
Exit codes: 0 success, 1 bad input, missing template bundle, missing source, or write conflict.
miravo skill
Install the Miravo agent skill. See Miravo Skill.
miravo skill install
miravo skill install [--claude] [--agents] [--project] [--force]Write the skill files, which are built into the binary, to ~/.claude/skills/miravo (Claude Code) and ~/.agents/skills/miravo (Codex and other Agent Skills tools). Each path written is listed. An install that already matches is reported as up to date.
| Option | Purpose |
|---|---|
--claude | Only the Claude Code folder |
--agents | Only the .agents folder |
--project | Use ./.claude/skills/miravo and ./.agents/skills/miravo in the current folder |
--force | Overwrite an existing install whose content differs |
Side effects: writes files under the target folders. Without --force, nothing is written when any target differs.
Exit codes: 0 success, 1 an existing install differs and --force was not passed.
miravo le
Work with Litmus Edge: export import files, apply a template, clean up managed resources, and manage saved targets. In the browser, use Console integrations.
| Command | Purpose |
|---|---|
le export template | Write Litmus Edge template JSON and tag CSV |
le export tags | Print runtime tags as DeviceHub CSV |
le export dt | Print one Digital Twins model as JSON |
le apply | Create or update resources in Litmus Edge |
le cleanup | Delete Miravo-managed resources from Litmus Edge |
le target | Manage saved Litmus Edge targets |
The API token never goes on the command line. le apply and le cleanup read it from LITMUS_EDGE_API_TOKEN or from a saved target (--target <label>). le target add and le target update read it from stdin with --api-token-stdin.
miravo le export
Generate Litmus Edge import files from local content or a running factory. Subcommands: template, tags, dt.
miravo le export template
miravo le export template -t smart-factory| Flag | Default | Purpose |
|---|---|---|
-t, --template <id> | Required | Template id, name, or path |
--source-hostname <host> | localhost | Hostname Litmus Edge uses to reach Miravo, embedded in device endpoints |
--protocol <name> | All protocols | Export only opcua, modbus, or mqtt |
--exposed-port <protocol=port> | None | Host-mapped port Litmus Edge dials instead of the internal one, for example modbus=5502. Repeatable |
-o, --output <prefix> | Template id | Output prefix for .le-template.json and -tags.csv. With --protocol and no -o: <template-id>-<protocol> |
--force | Off | Overwrite existing output files |
--json | Off | Print { assetCount, protocolCounts, jsonPath, csvPath, warning? } as JSON instead of the summary lines |
Side effects: writes <prefix>.le-template.json and <prefix>-tags.csv covering every asset, and prints the asset count per protocol, for example Exported 11 asset(s) (opcua: 6, modbus: 3, mqtt: 2). It never overwrites existing files without --force, and writes nothing if any target exists. No running factory is required. Built-in templates use the same asset id generation as miravo load.
Each asset exports on its scoped protocol, so a template with mixed scopes produces one file with devices on several drivers. With --protocol, only that protocol is exported and assets scoped elsewhere are skipped. The command then prints a warning with the skipped count, a Fix that suggests omitting --protocol for one file with every asset, and the per-protocol commands. Without -o, --protocol opcua writes <template-id>-opcua.*, so per-protocol runs never overwrite each other.
Exit codes: 0 success, 1 bad local input, missing content, or an existing output file without --force.
miravo le export tags
miravo le export tags --device smart_factory_cnc_001 --protocol opcua| Flag | Default | Purpose |
|---|---|---|
--device <name> | Required | Device name written to the CSV deviceName column. A label, not a filter |
--protocol <name> | Required | opcua, modbus, or mqtt |
--asset <id> | All | Export one asset only |
-o, --output <file> | stdout | Write CSV to a file |
--force | Off | Overwrite the output file |
--admin-url <url> | URL order above | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: reads the runtime manifest and prints or writes CSV. Needs a running factory.
Exit codes: 0 success, 1 bad local input or an existing output file without --force, 2 manifest transport failure.
miravo le export dt
miravo le export dt centrifugal-pump| Flag | Default | Purpose |
|---|---|---|
<model> | Required | Model name to export |
-o, --output <file> | stdout | Write JSON to a file |
--force | Off | Overwrite the output file |
Side effects: reads the local model YAML and prints or writes one Digital Twins model JSON in the Litmus Edge format. No running factory is required.
Exit codes: 0 success, 1 bad local input, missing model, or an existing output file without --force.
miravo le apply
Create or update Miravo resources in Litmus Edge. In the browser, use Console integrations.
miravo le apply --target demo -t smart-factory --dry-run| Flag | Purpose |
|---|---|
--target <label> | Use a saved target |
-t, --template <id|path> | Template to provision (required) |
--source-hostname <host> | Address Litmus Edge uses to reach Miravo |
--exposed-port <protocol=port> | Host-mapped port Litmus Edge dials, for example modbus=5502. Repeatable |
--protocol <name> | mqtt, opcua, or modbus |
--scope <scope> | Limit the plan to some resource types |
--dry-run | Print the plan without applying it |
-y, --yes | Skip the confirmation prompt |
The API token comes from LITMUS_EDGE_API_TOKEN, then the saved target. There is no token flag.
Side effects: a dry run only plans. A real run checks Litmus Edge auth, resolves the desired state, prints the plan, asks for confirmation, then creates or updates Miravo-managed devices, tags, and Digital Twins resources. If the plan has blockers, nothing is applied. Existing Digital Twins models with the same name count as unchanged, so after a schema change run le cleanup and then le apply.
Exit codes: 0 success, 1 invalid input, blockers, or failed plan entries, 2 integration transport failure, 3 integration rejection.
miravo le cleanup
Delete Miravo-managed resources from Litmus Edge. -t removes what an offline le apply -t of that template created, not what the Console applied for a running factory. In the browser, use Console integrations.
miravo le cleanup --target demo -t smart-factory --dry-run| Flag | Purpose |
|---|---|
-t, --template <id|path> | Scope cleanup to one template (offline apply) |
--all-managed | Remove all Miravo-managed resources |
--scope <scope> | Limit cleanup to some resource types |
--dry-run | Print the cleanup plan without deleting |
-y, --yes | Confirm a real cleanup |
The API token comes from LITMUS_EDGE_API_TOKEN, then the saved target. There is no token flag.
Side effects: a real run deletes managed assets, models, and devices in dependency order. It retries only transient transport failures.
Exit codes: 0 success, 1 invalid input, missing confirmation, or cleanup failures, 2 integration transport failure, 3 integration rejection.
miravo le target
Manage saved Litmus Edge targets. Subcommands: list, add, inspect, update, remove, test. In the browser, use Console integrations.
Targets live in ~/.miravo/integrations/targets.json. Commands that take <idOrLabel> match an exact id first, then a label ignoring case.
Side effects: add, update, and remove change the saved target store. remove prompts on a terminal unless --yes is set, and non-interactive runs require --yes. test sends a lightweight Litmus Edge probe and reports the detected version.
Exit codes: 0 success, 1 bad input or failed connectivity test, 2 integration transport failure.
miravo le target list
miravo le target list| Flag | Default | Purpose |
|---|---|---|
--json | Off | Machine-readable output |
miravo le target add
printf %s "$LE_TOKEN" | miravo le target add --label demo --hostname 10.0.0.20 --source-hostname 172.17.0.1 --api-token-stdin| Flag | Default | Purpose |
|---|---|---|
--label <label> | Required | Target label |
--hostname <host> | Required | Litmus Edge hostname or IP |
--source-hostname <host> | Required | Hostname Litmus Edge uses to reach Miravo |
--api-token-stdin | Off | Read the API token from stdin. When omitted on a terminal, a hidden prompt asks for it |
--json | Off | Machine-readable output |
There is no --api-token flag. A token on the command line leaks into shell history and process listings.
miravo le target inspect
miravo le target inspect demo| Flag | Default | Purpose |
|---|---|---|
--show-token | Off | Print the full stored token |
--json | Off | Machine-readable output |
miravo le target update
miravo le target update demo --hostname 10.0.0.21Pass at least one flag.
| Flag | Default | Purpose |
|---|---|---|
--label <label> | Unset | New label |
--hostname <host> | Unset | New Litmus Edge hostname or IP |
--api-token-stdin | Off | Read the new API token from stdin |
--source-hostname <host> | Unset | New source hostname |
--json | Off | Machine-readable output |
miravo le target remove
miravo le target remove demo| Flag | Default | Purpose |
|---|---|---|
-y, --yes | Off | Skip the confirmation prompt |
miravo le target test
miravo le target test demo| Flag | Default | Purpose |
|---|---|---|
--json | Off | Machine-readable output |
Reference
Exit codes
| Exit code | Meaning |
|---|---|
0 | Command succeeded |
1 | Usage error: unknown command or flag, missing or extra argument, bad value, missing terminal, confirmation, or credentials, content not found, or write conflict |
2 | Transport failure: Miravo, Litmus Edge, or a broker is unreachable, timed out, or refused authentication |
3 | Validation failure, strict lint warning, or the factory or integration rejected the request |
4 | Internal error (a bug). Re-run with --debug and report it |
130 | Interrupted with Ctrl+C during logs or status --watch |
Errors
Errors go to stderr as one error: line and, when there is a next step, one fix: line. They are lowercase with no trailing period, name commands in single quotes, and carry no log level or component prefix. Stdout stays empty, so a pipe never sees a half result.
error: no Miravo factory found for MIRAVO_HOME=/home/me/.miravo
fix: start one with 'miravo start', or pass --admin-url / set MIRAVO_ADMIN_URLAn unknown command or flag prints the error, a close match when there is one, and a pointer to the right --help. It never dumps the full help. miravo and miravo <group> without a subcommand print help on stdout and exit 0. -h on a command that does not exist is still an unknown-command error.
error: unknown command 'sttart'
Did you mean 'start'?
Run 'miravo --help' for the command list.With --json, the error is a single-line envelope on stderr, including for usage errors:
{"error":{"code":"TRANSPORT_ERROR","message":"cannot reach Miravo at http://127.0.0.1:9090","hint":"Start one with 'miravo start', or pass --admin-url <url>.","exitCode":2}}code is USAGE, NOT_FOUND, TRANSPORT_ERROR, TIMEOUT, VALIDATION_ERROR, REJECTED (the runtime refused a command), INTERNAL_ERROR, or the code the admin API returned. diagnostics lists schema problems with file, path, line, and hint. validate and lint report their verdict as a result on stdout with exit 3, not as an error envelope. Results and confirmations, such as Engine paused. or Created template bundle, go to stdout and are hidden by --quiet. Progress lines and warnings (warning:) go to stderr. --plain, NO_COLOR, and TERM=dumb remove color and the start summary box.
Help
miravo --help groups commands (Run, Operate a running factory, Content, Integrate, Shell) and starts with examples. Every command's --help shows its examples before the options and ends with a link to its section on this page. Option descriptions end with [default: x], [env: X], or [required] when they apply.
| Surface | Running factory needed |
|---|---|
start, init, validate, lint, templates, models, skill, completion, le export template, le export dt | No |
status, stop, logs, spawn, remove, pause, resume, speed, load, unload, reset, inject, adapter, le export tags | Yes. The factory in MIRAVO_HOME is found automatically |
le apply, le cleanup, le target * | No. They talk to Litmus Edge and the local template bundle store |
-n is --name on start and nothing else. --dry-run has no short form.
Related pages
Integrations
External integration command families.
Litmus Edge
Workflow for le apply, le cleanup, and le export.
Environment variables
Defaults and precedence for MIRAVO_* and LITMUS_EDGE_*.
Logging
Output format, NDJSON, and debug traces.
Was this page useful?
Last updated on
Miravo