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:

  • update asks before installing only when stdin is a terminal and --json is 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 --json prints current, channel, latest (version, tag, breaking), update_available, updated, and not_updated, which is why a newer release was not installed, or null.
  • 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. Set VRTMV_NO_UPDATE_CHECK=1 to skip the check.

Exit codes

ExitMeans
0Done, and nothing in the result fails.
1An error (on stderr), or a result that fails: see the command's row.
2A 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.
6The 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.
101vrtmv itself failed (a panic). Report it.

The codes other than 0, 1, 2 and 6 belong to the commands that name them below.

Command--jsonExit codes
assessyes0, 1 error.
verifyyes0 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-scanyes0 whatever it finds, 1 error; with --sign, 6 when the report could not be signed.
migrateyes0; 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).
runno0 done; 3 target-limited; 1 blocked, failed or an error.
run-statusyes0 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.
inventoryyes0, 1 error.
driftyes0; 1 error, or the source has no seat or entitlement.
soak observeno0 this reading held; 1 it did not, could not be measured, or an error.
soak summariseyes0 the window passes; 1 a break, inconclusive, or an error.
assess-fleetyes0; 1 a host could not be read (the report is still printed), or an error.
data discoveryes0, 1 error.
data planyes0; 1 error, or a --verify-dest tally that does not hold. A REFUSED item does not change the exit without --verify-dest.
data preservedno0, 1 error.
data upgrade-pathyes0 a path, or already at that version ([] with --json); 1 no path, no curated step, or an error.
data db-planyes0; 1 a database is refused, or an error.
probe recordyes0 every probe answered; 1 one did not (the record is still written), or an error.
resolveyes0, 1 error.
translateyes0, even with NO TARGET or NOT CURATED rows; 1 error.
config-pathsyes0, 1 error.
licenseyes0; 1 a host is refused, or an error.
readiness--format json writes the report file0, 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 file0, 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 file0; 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-verifyyes0 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-migrateno0, a refused runbook included; 1 error.
container-fleetyes0; 1 a workload or host is not ok, or an error.
patchyes0; 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-imageno0 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.
deployno0, 1 error.
identityno0, 1 error.
operator subscribeyes0, 1 error.
updateyes0 up to date, updated, or not updated (see above); 1 error.
usage, authno0, 1 error. auth exits 0 whether or not a token is stored.
docsno0, an unknown topic included.
reportno0 when the bundle is written, whatever the command it re-ran returned (that code is in the bundle); 1 nothing written.
console, remediateno0; 1 error, or stdin is not a terminal.
ui, panel, mcpnoServers: 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.