Scripts and agents
What a script, a CI job or an AI agent driving vrtmv can rely on: JSON on stdout, no prompt it cannot answer, and an exit code that says what happened.
JSON
Most commands take --json. With it, stdout holds one JSON document and nothing else. Progress, notes and the paths written go to stderr. The table below says which commands take --json.
The shape of each document is fixed within a release line. A key is not renamed or removed and a value does not change its type without a release note. New keys can appear, so read the keys you need and ignore the rest. vrtmv's own tests check the shapes on every change.
A command that fails with an error prints an error: … line to stderr and exits 1. When the error comes before any output, stdout is empty. When it comes after, stdout already holds what was printed: verify and cve-scan print the report and then fail to write --out, for one. A command whose report is a failing verdict (a verify that is not equivalent, a fleet with a host that could not be read) prints the report and exits non-zero. So read the exit code first. Take stdout as the answer only when the exit code is 0, or one the command's row below gives for a report.
patch --apply --json prints one document, {"plan": …, "apply": …}: the plan as patch --json prints it, and the outcome of the apply. The ansible-playbook output of patch --apply and run goes to stderr.
data upgrade-path --json prints a JSON array of paths, and [] when the database is already at that version.
Prompts
Two commands are interactive: console (and bare vrtmv) and remediate. When stdin is not a terminal they refuse at once with exit 1 and say what to use instead. Nothing else asks a question, with one exception:
updateasks before installing only when stdin is a terminal and--jsonis not given. Otherwise it installs only with--yes. Without it, it prints that an update is available and that it was not installed, and exits 0.update --jsonprintscurrent,channel,latest(version,tag,breaking),update_available,updated, andnot_updated, which is why a newer release was not installed, ornull.- The update notice every command prints on stderr when a newer release exists offers to install it only when stdin, stdout and stderr are all terminals and the command line does not give
--json. SetVRTMV_NO_UPDATE_CHECK=1to skip the check.
Exit codes
| Exit | Means |
|---|---|
| 0 | Done, and nothing in the result fails. |
| 1 | An error (on stderr), or a result that fails: see the command's row. |
| 2 | A usage error: an unknown flag, a missing argument, a group command (data, soak, probe, operator) with no subcommand. stderr says what was wrong, or for a group with no subcommand prints the group's help. attest-image also exits 2 for a refused run, below. |
| 6 | The command wrote its output and could not get it signed: migrate, cluster-migrate --emit-roles, and verify, cluster-verify, cve-scan and patch with --sign. stderr says why. It replaces every exit that would have passed; an exit that already fails (1, or verify's 4) is kept. --allow-unsigned turns it into a warning. |
| 101 | vrtmv itself failed (a panic). Report it. |
The codes other than 0, 1, 2 and 6 belong to the commands that name them below.
| Command | --json | Exit codes |
|---|---|---|
assess | yes | 0, 1 error. |
verify | yes | 0 equivalent and every gate holds; 3 target-limited (only without --require, and only with no preserved-as-is lane); 4 a --required class is not equivalent; 5 a preserved-as-is lane passed; 1 anything else, an error included. With a lane it exits only 5, 4 or 1: a target-limited verdict without --require is 1. A data, probe or chart gap turns 0, 3 or 5 into 1. With --borrow-from, a borrowed verdict exits 0 when it is equivalent and 1 otherwise, never 3, 4 or 5. With --sign, 6 in place of 0, 3 or 5 when the report could not be signed. See verify. |
cve-scan | yes | 0 whatever it finds, 1 error; with --sign, 6 when the report could not be signed. |
migrate | yes | 0; 1 error, or a plan that is BLOCKED (its files are still written); 6 the attestation could not be signed (its files are still written). |
run | no | 0 done; 3 target-limited; 1 blocked, failed or an error. |
run-status | yes | 0 when the run's record could be read, whatever it says; 1 no readable record. With --watch: 0 when the run finished with no error (target-limited too), 1 otherwise. |
inventory | yes | 0, 1 error. |
drift | yes | 0; 1 error, or the source has no seat or entitlement. |
soak observe | no | 0 this reading held; 1 it did not, could not be measured, or an error. |
soak summarise | yes | 0 the window passes; 1 a break, inconclusive, or an error. |
assess-fleet | yes | 0; 1 a host could not be read (the report is still printed), or an error. |
data discover | yes | 0, 1 error. |
data plan | yes | 0; 1 error, or a --verify-dest tally that does not hold. A REFUSED item does not change the exit without --verify-dest. |
data preserved | no | 0, 1 error. |
data upgrade-path | yes | 0 a path, or already at that version ([] with --json); 1 no path, no curated step, or an error. |
data db-plan | yes | 0; 1 a database is refused, or an error. |
probe record | yes | 0 every probe answered; 1 one did not (the record is still written), or an error. |
resolve | yes | 0, 1 error. |
translate | yes | 0, even with NO TARGET or NOT CURATED rows; 1 error. |
config-paths | yes | 0, 1 error. |
license | yes | 0; 1 a host is refused, or an error. |
readiness | --format json writes the report file | 0, even with hosts in error (reached, but their image, target or plan failed; counted in the report's error total); 1 error, or a host that was not measured (unreachable, or sudo refused) or not scanned (--stop-on-error). |
cve-scan-fleet | --format json writes the report file | 0, even with hosts that could not be scanned or reached (counted in the report); 1 error, hosts --stop-on-error left unscanned, or a host refused for sharing another's identity. |
cluster-migrate | --format json writes the report file | 0; 1 error, a source not scanned (even with --continue-on-error), or with --emit-roles a host refused a runnable role (coupled or of undetermined coupling, no identity stamp, or not enrolled); 6 with --emit-roles, a host's attestation could not be signed. |
cluster-verify | yes | 0 every host equivalent; 1 otherwise, or an error; with --sign, 6 when every host is equivalent and a representative's report could not be signed. |
coupled-migrate | no | 0, a refused runbook included; 1 error. |
container-fleet | yes | 0; 1 a workload or host is not ok, or an error. |
patch | yes | 0; 1 error, or with --apply a targeted CVE still present or a failed Ansible run; with --sign, 6 when the plan could not be signed. |
attest-image | no | 0 matches, statement written and signed (or --no-sign); 1 does not match, nothing written; 3 written and not signed; 2 the run was refused or failed (an argument, the key, cosign, COSIGN_REPOSITORY, an unreadable image). See attest-image. |
deploy | no | 0, 1 error. |
identity | no | 0, 1 error. |
operator subscribe | yes | 0, 1 error. |
update | yes | 0 up to date, updated, or not updated (see above); 1 error. |
usage, auth | no | 0, 1 error. auth exits 0 whether or not a token is stored. |
docs | no | 0, an unknown topic included. |
report | no | 0 when the bundle is written, whatever the command it re-ran returned (that code is in the bundle); 1 nothing written. |
console, remediate | no | 0; 1 error, or stdin is not a terminal. |
ui, panel, mcp | no | Servers: they run until stopped; 1 when one cannot start. mcp's stdout is the MCP stream. |
New to vrtmv? Sign up free for 10 migrations, or get a free assessment: run it on one hard host and we review the parity report with you.