MiravoCLI Reference
Command reference for miravo: lifecycle control, runtime mutations, exports, content inspection, and platform operations.
Control the environment lifecycle, mutate a running environment, inspect content, and automate platform work from shells, CI jobs, health checks, and recovery scripts.
Global options
| Option | Purpose |
|---|---|
--debug | Print stack traces for unexpected failures |
--verbose | Shorthand for --log-level debug |
--quiet | Suppress all output except errors |
--plain | Keep stable plain text output |
--log-level <level> | Select debug, info, warn, or error |
--log-format <format> | Select pretty or json |
Commands
| Group | Commands |
|---|---|
| Lifecycle | start · stop · pause · resume · speed · load · reset |
| Inspection | status · logs |
| Instances | spawn · remove · inject |
| Adapters | adapter |
| Content | init · add · validate · lint · catalog · models · templates |
| Platform | export · apply · cleanup · platforms |
| Shell | completion |
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. It does not call Miravo while completing.
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 completion file.
| Argument | Purpose |
|---|---|
shell | bash, zsh, or fish |
Side effects: writes the script to stdout. The redirection creates the completion file.
Exit codes: 0 success, 1 unsupported shell.
miravo start
Start an environment from a built-in template, a local template, none for a stateless empty boot, or a comma-separated template list.
miravo start -t smart-factoryUse none by itself. If no --name or MIRAVO_NAME is set, Miravo generates an environment name. It cannot be combined with comma-separated template lists.
miravo start -t smart-factory,water-treatment| Flag | Purpose |
|---|---|
-t, --template <id|name|path,...> | Pick the boot template, use none by itself for a stateless zero-instance boot, or pass a comma-separated boot+load list |
-n, --name <name> | Override the generated or derived environment name |
-d, --detach | Run detached in background and return to shell |
--dry-run | Validate config and print the summary without starting |
--no-input | Disable prompts and use non-interactive defaults |
-s, --speed <multiplier> | Set the time multiplier |
--no-mqtt | Disable the embedded MQTT broker |
| Flag | Default | Purpose |
|---|---|---|
-n, --name <name> | Template/namespace derived or generated | Environment name |
-t, --template <id|name|path,...> | Auto-detected | Environment id, name, path, none by itself for stateless empty boot, or comma-separated list |
-s, --speed <multiplier> | 1 | Time multiplier |
--seed <number> | Random | Deterministic RNG seed |
--tick <ms> | 1000 | Tick interval |
-p, --mqtt-port <number> | 1883 | MQTT port |
--mqtt-host <host> | 0.0.0.0 | MQTT bind host |
--mqtt-mode <mode> | embedded | MQTT mode: embedded or external |
--mqtt-url <url> | Unset | External MQTT broker URL |
--mqtt-username <username> | Unset | External MQTT username |
--mqtt-password <password> | Unset | External MQTT password |
--no-mqtt | Enabled | Disable MQTT |
--opcua | Disabled unless template enables it | Enable OPC UA |
--opcua-port <number> | 4840 | OPC UA port |
--opcua-host <host> | Adapter default | OPC UA bind host |
--modbus | Disabled unless template enables it | Enable Modbus TCP |
--modbus-port <number> | 1502 | Modbus port |
--modbus-host <host> | Adapter default | Modbus bind host |
--admin-host <host> | 127.0.0.1 | Admin bind host |
--admin-port <number> | 8080 | Admin bind port |
-d, --detach | false | Start as one detached process |
--dry-run | false | Validate without starting |
--no-input | false | Disable prompts |
--no-ui | UI enabled | Disable the embedded Console |
--no-auth | Auth enabled | Disable admin auth |
--reset-state | false | Ignore any saved snapshot |
--summary-interval <seconds> | 5 | Seconds between summary lines |
Side effects: starts the engine, admin server, enabled adapters, and the embedded Console unless --no-ui is set. Detached mode writes runtime metadata under ~/.miravo.
Exit codes: 0 success or dry-run validation, 1 invalid input or config, 2 startup dependency failure.
miravo status
Read live engine health, metrics, and instance details from a running environment.
miravo status| Flag | Purpose |
|---|---|
--watch | Poll every second and redraw until interrupted |
--instance <id> | Focus on one instance |
--json | Emit machine-readable JSON |
--discover | Discover runtimes over MQTT and exit |
| Flag | Default | Purpose |
|---|---|---|
--name <name> | Unset | Target one environment name |
--discover | false | Discover and exit |
-w, --watch | false | Poll for updates |
--instance <id> | Unset | Show one instance |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--template <path> | MIRAVO_TEMPLATE | MQTT discovery connection info |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: read-only. --discover uses MQTT instead of the admin server.
Exit codes: 0 success, 1 invalid admin URL or bad local input, 2 transport failure, 3 runtime rejection.
miravo stop
Stop detached runtime or an explicit admin target.
miravo stop| Flag | Default | Purpose |
|---|---|---|
--admin-url <url> | URL precedence chain | Override the admin target |
--json | false | Machine-readable output |
--timeout <seconds> | 10 | Shutdown timeout |
Side effects: stops the detached target and clears the local detached pointer when that target matches the local runtime.
Exit codes: 0 success, 1 local target resolution failure, 2 transport failure, 3 runtime rejection.
miravo logs
Stream runtime events over WebSocket from a detached pointer or explicit admin target.
miravo logs| Flag | Default | Purpose |
|---|---|---|
--tail <n> | Unset | Fetch the last n events before streaming |
--channels <list> | faults,lifecycle,instances,engine,adapters | Restrict channels (tick also supported) |
--json | false | Emit NDJSON |
--admin-url <url> | URL precedence chain | Override the admin target |
Side effects: opens a streaming connection and keeps the process attached until interrupted.
Exit codes: 0 clean stream shutdown, 1 local target resolution failure, 2 transport failure.
miravo spawn
Add new instances from a model name.
miravo spawn centrifugal-pump| Flag | Default | Purpose |
|---|---|---|
-c, --count <n> | 1 | Number of instances to create |
--name <instance-id> | Unset | Exact runtime instance id when count is 1 |
--prefix <prefix> | Model-derived | Generate ids like <prefix>-001 |
--protocols <list> | Enabled adapters | Limit exposure to mqtt, opcua, and/or modbus |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: creates new instances. Re-running the command creates more. Use --name for one exact id, --prefix to avoid shared defaults like motor-001, and --protocols mqtt,opcua to scope exposure.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo remove
Remove one instance by id.
miravo remove pump-003miravo remove pump-003 --yes| Flag | Default | Purpose |
|---|---|---|
--yes | false | Skip the confirmation prompt |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: deletes the instance. TTY 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 environment without destroying state.
miravo pause| Flag | Default | Purpose |
|---|---|---|
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: stops tick advancement while keeping runtime state in memory.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo resume
Resume a paused environment.
miravo resume| Flag | Default | Purpose |
|---|---|---|
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: restarts tick advancement for the current runtime.
Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.
miravo speed
Set the time multiplier on a running environment.
miravo speed 10| Flag | Default | Purpose |
|---|---|---|
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: changes runtime speed immediately.
Exit codes: 0 success, 1 invalid multiplier or bad local input, 2 transport failure, 3 runtime rejection.
miravo load
Load additional instances into a running environment.
miravo load -t smart-factory| Flag | Purpose |
|---|---|
templateArg | Template id, name, path, or - for stdin |
-t, --template <id|name|path,...> | Template selector when no positional arg is used |
-c, --count <n> | Number of copies to load per template |
--name-prefix <prefix> | Prefix generated runtime ids with <prefix>-... |
--dry-run | Print the load request without sending it |
| Flag | Default | Purpose |
|---|---|---|
templateArg | Unset | Template id, name, path, or - for stdin |
-t, --template <id|name|path,...> | MIRAVO_TEMPLATE | Environment selector |
-c, --count <n> | 1 | Copies to load per template |
--name-prefix <prefix> | Template id | Prefix generated runtime ids |
--dry-run | false | Print without mutating runtime |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: creates additional instances or template runs. Re-running the same command adds more runtime content.
Exit codes: 0 success or dry run, 1 bad input or missing template, 2 transport failure, 3 runtime rejection.
miravo reset
Remove all instances and template runs.
miravo reset| Flag | Default | Purpose |
|---|---|---|
--clear-persistence | false | Remove saved state for the next boot |
--yes | false | Skip the confirmation prompt |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: clears in-memory runtime state. --clear-persistence also removes the persisted snapshot. TTY 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 faults on a running instance.
miravo inject| Flag | Default | Purpose |
|---|---|---|
--clear | false | Clear the named fault instead of triggering it |
--json | false | Machine-readable output |
--name <name> | Unset | Target one environment name |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: mutates runtime fault state. No positional args opens the interactive picker on a TTY.
Exit codes: 0 success, 1 bad input or missing TTY for interactive mode, 2 transport failure, 3 runtime rejection.
miravo adapter
Manage runtime protocol adapters.
enable
miravo adapter enable mqtt| Flag | Default | Purpose |
|---|---|---|
-p, --port <number> | Adapter default | Override the adapter port |
--host <host> | Adapter default | Override the bind host |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
disable
miravo adapter disable opcua| Flag | Default | Purpose |
|---|---|---|
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
inspect
miravo adapter inspect modbus --json| Flag | Default | Purpose |
|---|---|---|
name | modbus | Inspect one adapter surface |
--json | false | Machine-readable output |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: enable and disable mutate 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 export
Export platform payloads from local content or a running environment. The subcommand prefix identifies the target platform — le-* subcommands target Litmus Edge. Console alternative: Console platforms.
le-template
miravo export le-template -t smart-factory| Flag | Default | Purpose |
|---|---|---|
-t, --template <id> | Required | Environment id, name, or path |
--host <hostname> | localhost | Source hostname embedded in device endpoints |
--protocol <name> | Template protocol | Override protocol to opcua, modbus, or mqtt |
--name-prefix <prefix> | Template id | Prefix generated runtime ids and LE aliases before underscore conversion |
-o, --output <prefix> | Template id | Output prefix for .le-template.json and -tags.csv |
Side effects: writes <prefix>.le-template.json and <prefix>-tags.csv. No running environment is required. For catalog/env templates, export uses the same env-aware runtime ID generation as miravo load. --name-prefix overrides that shared prefix.
le-tags
miravo export le-tags --device DTW-FAB-PLC --protocol opcua| Flag | Default | Purpose |
|---|---|---|
--device <name> | Required | Litmus Edge device name |
--protocol <name> | Required | opcua, modbus, or mqtt |
--instance <id> | All | Restrict export to one instance |
-o, --output <file> | stdout | Write CSV to a file |
--admin-url <url> | URL precedence chain | Override the admin target |
--timeout <seconds> | 5 | Admin request timeout |
Side effects: reads the runtime manifest and prints or writes CSV.
le-dt
miravo export le-dt centrifugal-pump| Flag | Default | Purpose |
|---|---|---|
model | Required | Model name to export |
-o, --output <file> | stdout | Write JSON to a file |
Side effects: reads the local model YAML and prints or writes one Digital Twins model JSON in the Litmus Edge format. No running environment is required.
Exit codes: 0 success, 1 bad local input or missing local content, 2 manifest transport failure for le-tags.
miravo apply
Apply Miravo resources to an external platform. The first argument is the platform target. Use le or litmus-edge for Litmus Edge. More platforms are in the works. Console alternative: Console platforms.
miravo apply le --target demo --template smart-factory --dry-run| Flag | Purpose |
|---|---|
--target <label> | Use a saved platform environment |
--template <path> | Pick the template to provision |
--source-hostname <host> | Set the address the platform uses to reach Miravo |
--name-prefix <prefix> | Prefix generated runtime ids and LE device / DT instance aliases |
--protocol <name> | Pick mqtt, opcua, or modbus |
--scope <scope> | Limit the plan to selected resource types |
--dry-run | Print the plan without applying it |
| Flag | Default | Purpose |
|---|---|---|
--target <label> | Unset | Named environment from ~/.miravo/platforms/targets.json |
--le-hostname <host> | LITMUS_EDGE_HOSTNAME or saved env | Litmus Edge hostname or IP |
--le-api-token <token> | LITMUS_EDGE_API_TOKEN or saved env | Litmus Edge API token |
--template <path> | Required | Template name or file path |
--name-prefix <prefix> | Template id | Prefix generated runtime ids and LE aliases |
--protocol <name> | Template protocol or opcua | Protocol |
--scope <scope> | devices,models,instances | Resource scope |
--area <name> | Unset | Filter by area name |
--line <name> | Unset | Filter by line name |
--instance <id> | Unset | Filter by instance id |
--source-hostname <host> | MIRAVO_SOURCE_HOSTNAME or saved env | Source hostname |
--if-unmanaged <policy> | fail | Collision policy: fail or skip |
--dry-run | false | Print the plan only |
--json | false | Emit JSON plan |
Side effects: dry-run only plans. A mutating run checks platform auth, resolves the desired state, then creates or updates Miravo-managed devices and instances. Existing single-name Digital Twins models are treated as unchanged; schema changes require cleanup then apply.
Exit codes: 0 success, 1 invalid input, blockers, or plan failures, 2 platform transport failure, 3 remote platform rejection.
miravo cleanup
Delete Miravo-managed resources from an external platform. The first argument is the platform target. Use le or litmus-edge for Litmus Edge. More platforms are in the works. Console alternative: Console platforms.
miravo cleanup le --target demo --template smart-factory --dry-run| Flag | Purpose |
|---|---|
--template <path> | Scope cleanup to one template |
--all-managed | Remove all Miravo-managed resources |
--scope <scope> | Limit cleanup to selected resource types |
--dry-run | Print the cleanup plan without deleting |
--yes | Confirm a mutating cleanup |
| Flag | Default | Purpose |
|---|---|---|
--target <label> | Unset | Named environment from ~/.miravo/platforms/targets.json |
--le-hostname <host> | LITMUS_EDGE_HOSTNAME or saved env | Litmus Edge hostname or IP |
--le-api-token <token> | LITMUS_EDGE_API_TOKEN or saved env | Litmus Edge API token |
--template <path> | Required unless --all-managed | Template name or file path |
--scope <scope> | instances,models,devices | Resource scope |
--area <name> | Unset | Filter by area name |
--line <name> | Unset | Filter by line name |
--instance <id> | Unset | Filter by instance id |
--all-managed | false | Ignore template scoping and remove all managed resources |
--dry-run | false | Print the plan only |
--json | false | Emit JSON plan |
--yes | false | Skip the confirmation prompt |
Side effects: a mutating run deletes managed instances, models, and devices in dependency order. The command only retries transient platform transport failures before it exits.
Exit codes: 0 success, 1 invalid input, missing confirmation, or cleanup failures, 2 platform transport failure, 3 remote platform rejection.
miravo platforms
Manage saved platform environments. Console alternative: Console platforms.
Saved targets live under ~/.miravo/platforms/targets.json. The command resolves exact ids first, then case-insensitive exact labels.
Side effects: add, update, and remove mutate the saved target store. remove prompts on TTY unless --yes is set; non-interactive runs require --yes. test sends a lightweight Litmus Edge probe.
Exit codes: 0 success, 1 bad input or failed connectivity test, 2 external platform transport failure.
miravo init
Create an environment folder with one root .miravo.yaml entry file. With --from, copy the entry file from a built-in id, a namespaced environment, or an absolute environment folder. Built-in forks keep model references shared. Local and namespaced forks also copy sibling .twin.yaml overrides.
miravo init packaging-line| Argument or flag | Purpose |
|---|---|
name | Environment 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. |
Side effects: writes an environment folder. init has no --json output.
Exit codes: 0 success, 1 bad input, missing source, or write conflict.
miravo add
Add one .twin.yaml model file to an environment. Without --from, Miravo creates a blank model scaffold. With --from, it copies a shared built-in model, a model from a namespaced environment, or an absolute .twin.yaml file.
miravo add coolant-pump --in packaging-line| Argument or flag | Purpose |
|---|---|
model | New local model name. The output filename is <model>.twin.yaml. |
--in <id> | Target environment id. Defaults to the current environment folder. |
--from <src> | Copy from <builtin-model-id>, <namespace>/<env-id>/<model>, or /abs/path/to/file.twin.yaml. |
Side effects: writes one sibling .twin.yaml file. add has no --json output.
Exit codes: 0 success, 1 bad input, missing environment, missing source, or write conflict.
miravo validate
Validate one environment folder. Validation checks the entry schema, model schemas, template-to-model references, and filename-to-model.name matches.
miravo validate| Argument or flag | Purpose |
|---|---|
id | Environment id, namespaced id, or path. Omit to validate the current environment. |
--json | Emit machine-readable diagnostics. |
Side effects: read-only.
Exit codes: 0 valid, 1 bad input or missing environment, 2 internal failure, 3 validation failed.
miravo lint
Run deterministic realism checks against one environment folder. Lint warnings do not block by default. Use --strict when warnings should fail CI.
miravo lint| Argument or flag | Purpose |
|---|---|
id | Environment id, namespaced id, or path. Omit to lint the current environment. |
--strict | Exit non-zero when warnings are found. |
--json | Emit 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. |
| Thermal tau | Temperature members jump too quickly or lack a time constant. | Model thermal lag with a first-order response or another slow generator. |
| 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. |
| 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, or enabled guard to the fault trigger. |
Side effects: read-only.
Exit codes: 0 clean or warnings in non-strict mode, 1 bad input or missing environment, 2 internal failure, 3 warnings found with --strict.
Lint never rewrites files. Fix the model or entry file, then run miravo validate and miravo lint again.
miravo catalog
Browse built-in environment starters and shared models. catalog is read-only and only shows built-in content.
Side effects: read-only.
Exit codes: 0 success, 1 missing built-in id or bad input.
miravo models
List or inspect discoverable asset models. miravo models and miravo models list do the same work. Output includes the source label for each model.
Side effects: read-only.
Exit codes: 0 success, 1 missing model or bad local path.
miravo templates
List or inspect discoverable environments. miravo templates and miravo templates list do the same work, and both show each environment source.
Side effects: list and inspect are read-only. remove deletes the environment folder. --purge-state also removes the persisted state snapshot. TTY runs prompt unless --yes is set. Non-interactive runs require --yes.
Exit codes: 0 success, 1 missing environment, bad input, or missing confirmation, 2 internal failure, 3 refused (built-in, multi-source, or running environment).
Reference
| Exit code | Meaning |
|---|---|
0 | Command succeeded |
1 | Bad arguments, bad local input, missing TTY, missing content, or write conflict |
2 | Transport, dependency, or internal environment failure |
3 | Validation failure, strict lint warning, runtime rejection, or platform rejection |
| Surface | Miravo runtime required |
|---|---|
start, init, add, validate, lint, catalog, models, templates, completion, export le-template, export le-dt | No |
status, stop, logs, spawn, remove, pause, resume, speed, load, reset, inject, adapter, export le-tags | Yes |
apply le / apply litmus-edge, cleanup le / cleanup litmus-edge, platforms target * | No Miravo runtime. Uses Litmus Edge or the local environment store |
Related pages
Platforms
External platform command families.
Litmus Edge
Full workflow for apply le, cleanup le, and export le-*.
Environment variables
Defaults and precedence for MIRAVO_* and LITMUS_EDGE_*.
Logging
Output format, NDJSON, and debug traces.
Was this page useful?
Last updated on