हर कमांड --json लेती है और stdout पर machine-readable आउटपुट देती है, stderr पर errors और meaningful exit code। shapes frozen हैं: हर object में apiVersion: 1 होता है, fields सिर्फ add होते हैं, और breaking change version बढ़ाता है। test suite इन्हें lock करती है।

आउटपुट sorted keys और ISO-8601 dates के साथ pretty-printed होता है।

Shapes

Shape	Commands
`VMSummaryJSON`	`list`, `info`, `create`
`SnapshotJSON`	`snapshot list`
`OperationJSON`	mutating commands — `snapshot`, `reset`, `clone`, `archive`, `rm`, …
`LogLineJSON`	`logs`
`AddressJSON`	`ip`
`DiskUsageReportJSON`	`du`
`GuideJSON`	`guide <guest>`

VMSummaryJSON में name, id, guest, state, cpuCount, memoryBytes, diskBytes, network, path, address, snapshotCount, isTemplate, waitingForDHCP और networkStatistics होते हैं। list --json archived machines को state: "archived" के साथ शामिल करता है।

OperationJSON में ok, operation, vm, detail और durationMilliseconds होते हैं — इसी से measured snapshot timings मिलती हैं, किसी की बात पर भरोसा नहीं करना पड़ता।

Exit codes

Code	Meaning
0	ok
1	failed
2	usage
3	not found
4	wrong state
5	unsupported

Destructive commands prompt की जगह exit 4 से refuse करती हैं। interactive prompts नहीं हैं, इसलिए script कभी human का इंतज़ार नहीं करती। जब सच में मतलब हो तब --force या --yes पास करें।

एक reliable script

गलती "running" को "ready" समझना है। wait-ready तब तक block करता है जब तक guest actually reachable न हो:

set -e
1vm create ci --from ubuntu-golden
1vm start ci --detach
1vm wait-ready ci
1vm exec ci -- ./run-tests.sh
1vm discard-session ci --force

एक कमांड में disposable machines

task run पूरा clone-wait-exec-dispose loop आपके लिए करता है:

1vm task run -- ./build.sh

यह pinned golden image clone करता है, readiness का wait करता है, command चलाता है और machine dispose कर देता है। Golden images template pin, template list और golden capture से manage होती हैं।

MCP

1VMTool Model Context Protocol बोलता है, इसलिए AI agent सीधे machines own और drive कर सकता है:

1vm mcp serve                      # JSON-RPC on stdio
1vm mcp install-snippet claude     # config JSON for a host
1vm agent gc                       # delete stopped agent-created machines

agent gc matter करता है: machines बनाने वाला agent उन्हें छोड़ नहीं देना चाहिए, और यही cleanup verb है।