CLI 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	`models` · `templates` · `fork`
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/miravo

For 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, or a comma-separated template list.

miravo start -t smart-factory

Flag	Purpose
`-t, --template <id\|name\|path,...>`	Pick the boot template or a comma-separated boot+load list
`-n, --name <name>`	Override the environment name
`-d, --detach`	Run as one background process
`--dry-run`	Validate config and print the summary without starting
`-s, --speed <multiplier>`	Set the time multiplier
`--no-mqtt`	Disable the embedded MQTT broker

Flag	Default	Purpose
`-n, --name <name>`	Template or namespace derived	Environment name
`-t, --template <id\|name\|path,...>`	Auto-detected	Template id, name, path, or comma-separated list
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root
`--models-dir <path>`	Unset	Extra model search path
`-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>`	`502`	Modbus port
`--modbus-host <host>`	Adapter default	Modbus bind host
`--admin-host <host>`	`0.0.0.0`	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-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 state, metrics, and instance details from a running environment.

miravo status

Flag	Purpose
`--watch`	Poll and redraw the status view
`--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

Request a clean shutdown from a detached environment.

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 domain events from a detached environment over WebSocket.

miravo logs

Flag	Default	Purpose
`--tail <n>`	Unset	Fetch the last `n` events before streaming
`--channels <list>`	All except `tick`	Restrict channels
`--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
`--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.

Exit codes: 0 success, 1 bad input, 2 transport failure, 3 runtime rejection.

miravo remove

Remove one instance by id.

miravo remove pump-003

miravo 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
`--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`	Template selector
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root
`-c, --count <n>`	`1`	Copies to load per template
`--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	Template id, name, or path
`--host <hostname>`	`localhost`	Source hostname embedded in device endpoints
`--protocol <name>`	Template protocol	Override protocol to `opcua`, `modbus`, or `mqtt`
`-o, --output <prefix>`	Template id	Output prefix for `.le-template.json` and `-tags.csv`
`--models-dir <path>`	Unset	Extra model search path
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root

Side effects: writes <prefix>.le-template.json and <prefix>-tags.csv. No running environment is required.

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
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root

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
`--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
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root
`--template <path>`	Required	Template name or file path
`--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, models, and instances.

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
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root for template resolution
`--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 retries failed cleanup attempts 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 models

List or inspect discoverable asset models. miravo models and miravo models list do the same work.

Side effects: read-only.

Exit codes: 0 success, 1 missing model or bad local path.

miravo templates

List or inspect discoverable templates. miravo templates and miravo templates list do the same work.

Side effects: read-only.

Exit codes: 0 success, 1 missing template or bad local path.

miravo fork

Copy a model or template into the local registry for customization.

model

miravo fork model centrifugal-pump

Flag	Default	Purpose
`--force`	`false`	Overwrite an existing local copy
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root

template

miravo fork template water-treatment

Flag	Default	Purpose
`--force`	`false`	Overwrite an existing local copy
`--models-only`	`false`	Fork only referenced models
`--catalog-dir <path>`	`MIRAVO_CATALOG_DIR`	Catalog root

Side effects: writes files under ~/.miravo/registry/local/models and ~/.miravo/registry/local/templates.

Exit codes: 0 success, 1 missing content or write conflict.

Reference

Exit code	Meaning
`0`	Command succeeded
`1`	Bad arguments, bad local input, missing TTY, missing content, or validation failure
`2`	Transport or environment failure
`3`	Runtime or external platform rejected the requested action

Surface	Miravo runtime required
`start`, `models`, `templates`, `fork`, `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

CLI Reference

Global options

Commands

miravo completion

miravo start

miravo status

miravo stop

miravo logs

miravo spawn

miravo remove

miravo pause

miravo resume

miravo speed

miravo load

miravo reset

miravo inject

miravo adapter

enable

disable

inspect

miravo export

le-template

le-tags

le-dt

miravo apply

miravo cleanup

miravo platforms

miravo models

miravo templates

miravo fork

model

template

Reference

Platforms

Litmus Edge

Environment variables

Logging

On this page

CLI Reference

miravo completion

miravo start

miravo status

miravo logs

miravo reset

miravo inject

miravo adapter

enable

disable

inspect

miravo export

le-template

le-tags

le-dt

miravo apply

miravo cleanup

miravo platforms

env list

env add

env inspect

env update

env remove

env test

miravo models

list

inspect

miravo templates

list

inspect

miravo fork

model

template

Platforms

Litmus Edge

Environment variables

Logging

On this page