MiravoMiravo

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

OptionPurpose
-V, --versionPrint the version
--debugPrint stack traces for unexpected failures
-q, --quietSuppress all output except errors
--plainUse stable plain-text output, no ANSI styling
--no-inputNever 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

GroupCommands
Runstart · stop · status · logs
Operate a running factorypause · resume · speed · inject · spawn · remove · load · unload · reset · adapter
Contentinit · validate · lint · templates · models
Integratele (Litmus Edge: export, apply, clean up, saved targets) · skill
Shellcompletion

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/miravo

For Zsh, keep ~/.zsh/completions in fpath before compinit:

fpath=(~/.zsh/completions $fpath)

Open a new shell after writing the file.

ArgumentPurpose
shellbash, 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-factory

With 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.

FlagPurpose
-t, --template <id|name|path,...>Boot template, none, or a comma-separated list
-n, --name <name>Factory name
-d, --detachRun in the background and return to the shell
--dry-runValidate config and print the summary without starting
--no-inputDisable prompts and use non-interactive defaults
-s, --speed <multiplier>Time multiplier
--run-for <duration>Pause at this simulated time (8h, 7d)
--no-mqttDisable 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
FlagPurpose
-w, --watchPoll every second and redraw until interrupted
--asset <id>Show detail for one asset
--jsonMachine-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
FlagDefaultPurpose
--admin-url <url>URL order aboveOverride the admin target
--jsonOffMachine-readable output
--timeout <seconds>10Shutdown 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
FlagDefaultPurpose
--tail <n>UnsetFetch the last n events (1 to 1000) before streaming. Other values are rejected with the allowed range
--no-followFollowPrint history and exit. Without --tail, prints the last 50 events
--channels <list>faults,lifecycle,assets,engine,adaptersComma-separated channels. tick is also available
--jsonOffEmit NDJSON
--admin-url <url>URL order aboveOverride 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
FlagDefaultPurpose
-c, --count <n>1Number of assets to create
--id <assetId>UnsetExact asset id when count is 1
--prefix <prefix>Model-derivedGenerate ids like <prefix>-001
--protocols <list>Enabled adaptersExpose only on mqtt, opcua, and/or modbus
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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-003
miravo remove pump-003 --yes
FlagDefaultPurpose
-y, --yesOffSkip the confirmation prompt
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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-factory

Without --template, Miravo looks for one template to load, using the same discovery as start.

FlagPurpose
-t, --template <id|name|path,...>Template id, name, path, comma-separated list, or - for stdin
--dry-runPrint the load request without sending it
-y, --yesSkip 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
FlagDefaultPurpose
-y, --yesOffSkip the confirmation prompt
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
-y, --yesOffSkip the confirmation prompt
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
--clearOffClear the fault instead of triggering it
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
<name>Requiredmqtt, opcua, or modbus
-p, --port <number>Adapter defaultOverride the adapter port
--host <host>Adapter defaultOverride the bind host
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin request timeout

disable

miravo adapter disable opcua
FlagDefaultPurpose
<name>Requiredmqtt, opcua, or modbus
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin request timeout

inspect

miravo adapter inspect modbus --json

Prints the tag map for one adapter. JSON output keeps only the requested adapter under each tag's protocols, matching the human output.

FlagDefaultPurpose
[name]modbusAdapter to inspect
--jsonOffMachine-readable output
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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 flagPurpose
[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.
--jsonPrint { 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 flagPurpose
[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.
--jsonMachine-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 flagPurpose
[id]Template bundle id, namespaced id, or path. Omit to lint the current folder.
--strictExit non-zero when warnings are found.
--jsonMachine-readable diagnostics.

Realism rules

RuleFlagsFix
Vibration couplingRotating 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 tauTemperature 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 overlayMaintenance 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-writeWritable members are modeled as observations.Keep operator-set values writable and model sensor observations as separate readable members.
Lifecycle stage jumpLifecycle stages skip directly across large wear intervals.Add intermediate stages or adjust thresholds so wear progression is gradual.
Observation scaleObserved 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 guardFaults 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
FlagPurpose
--source <source>Only templates from this source: builtin, personal, namespace, or cwd
--jsonMachine-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 flagPurpose
<idNameOrPath>Template bundle id, name, or path
--rawDump the raw YAML. Cannot be combined with --json
--jsonMachine-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
FlagPurpose
--purge-stateAlso delete ~/.miravo/state/<env>.json
-y, --yesSkip the confirmation prompt
--jsonMachine-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
FlagPurpose
--source <source>Only models from this source: builtin, personal, namespace, or cwd
--jsonMachine-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 flagPurpose
<name>Model name
--rawDump the raw YAML
--jsonMachine-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 flagPurpose
<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.
--jsonPrint { 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.

OptionPurpose
--claudeOnly the Claude Code folder
--agentsOnly the .agents folder
--projectUse ./.claude/skills/miravo and ./.agents/skills/miravo in the current folder
--forceOverwrite 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.

CommandPurpose
le export templateWrite Litmus Edge template JSON and tag CSV
le export tagsPrint runtime tags as DeviceHub CSV
le export dtPrint one Digital Twins model as JSON
le applyCreate or update resources in Litmus Edge
le cleanupDelete Miravo-managed resources from Litmus Edge
le targetManage 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
FlagDefaultPurpose
-t, --template <id>RequiredTemplate id, name, or path
--source-hostname <host>localhostHostname Litmus Edge uses to reach Miravo, embedded in device endpoints
--protocol <name>All protocolsExport only opcua, modbus, or mqtt
--exposed-port <protocol=port>NoneHost-mapped port Litmus Edge dials instead of the internal one, for example modbus=5502. Repeatable
-o, --output <prefix>Template idOutput prefix for .le-template.json and -tags.csv. With --protocol and no -o: <template-id>-<protocol>
--forceOffOverwrite existing output files
--jsonOffPrint { 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
FlagDefaultPurpose
--device <name>RequiredDevice name written to the CSV deviceName column. A label, not a filter
--protocol <name>Requiredopcua, modbus, or mqtt
--asset <id>AllExport one asset only
-o, --output <file>stdoutWrite CSV to a file
--forceOffOverwrite the output file
--admin-url <url>URL order aboveOverride the admin target
--timeout <seconds>5Admin 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
FlagDefaultPurpose
<model>RequiredModel name to export
-o, --output <file>stdoutWrite JSON to a file
--forceOffOverwrite 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
FlagPurpose
--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-runPrint the plan without applying it
-y, --yesSkip 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
FlagPurpose
-t, --template <id|path>Scope cleanup to one template (offline apply)
--all-managedRemove all Miravo-managed resources
--scope <scope>Limit cleanup to some resource types
--dry-runPrint the cleanup plan without deleting
-y, --yesConfirm 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
FlagDefaultPurpose
--jsonOffMachine-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
FlagDefaultPurpose
--label <label>RequiredTarget label
--hostname <host>RequiredLitmus Edge hostname or IP
--source-hostname <host>RequiredHostname Litmus Edge uses to reach Miravo
--api-token-stdinOffRead the API token from stdin. When omitted on a terminal, a hidden prompt asks for it
--jsonOffMachine-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
FlagDefaultPurpose
--show-tokenOffPrint the full stored token
--jsonOffMachine-readable output

miravo le target update

miravo le target update demo --hostname 10.0.0.21

Pass at least one flag.

FlagDefaultPurpose
--label <label>UnsetNew label
--hostname <host>UnsetNew Litmus Edge hostname or IP
--api-token-stdinOffRead the new API token from stdin
--source-hostname <host>UnsetNew source hostname
--jsonOffMachine-readable output

miravo le target remove

miravo le target remove demo
FlagDefaultPurpose
-y, --yesOffSkip the confirmation prompt

miravo le target test

miravo le target test demo
FlagDefaultPurpose
--jsonOffMachine-readable output

Reference

Exit codes

Exit codeMeaning
0Command succeeded
1Usage error: unknown command or flag, missing or extra argument, bad value, missing terminal, confirmation, or credentials, content not found, or write conflict
2Transport failure: Miravo, Litmus Edge, or a broker is unreachable, timed out, or refused authentication
3Validation failure, strict lint warning, or the factory or integration rejected the request
4Internal error (a bug). Re-run with --debug and report it
130Interrupted 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_URL

An 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.

SurfaceRunning factory needed
start, init, validate, lint, templates, models, skill, completion, le export template, le export dtNo
status, stop, logs, spawn, remove, pause, resume, speed, load, unload, reset, inject, adapter, le export tagsYes. 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.

Was this page useful?

Last updated on