每条命令都接受 --json，在 stdout 上输出机器可读结果，错误写入 stderr，并返回有意义的退出码。数据结构是冻结的：每个对象都带有 apiVersion: 1，字段只会增加，破坏性变更会提升版本号。测试套件锁定了这些约定。

输出会按排序后的键和 ISO-8601 日期进行格式化打印。

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 会包含已归档机器，状态为 state: "archived"。

OperationJSON 包含 ok、operation、vm、detail 和 durationMilliseconds——这就是获取实测快照耗时的方式，而不是听信口头说法。

Exit codes

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

破坏性命令会以退出码 4 拒绝执行，而不是弹出确认提示。设计上没有任何交互式提示，因此脚本不会因为等待人工输入而挂起。确认要执行时，请传入 --force 或 --yes。

可靠的脚本

常见错误是把“running”当成“ready”。wait-ready 会一直阻塞，直到 guest 真正可达：

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

一条命令完成一次性机器

task run 会替你完成整个 clone-wait-exec-dispose 循环：

1vm task run -- ./build.sh

它会克隆固定的 golden 镜像，等待就绪，执行命令，然后销毁机器。Golden 镜像通过 template pin、template list 和 golden capture 管理。

MCP

1VMTool 支持 Model Context Protocol，因此 AI agent 可以直接拥有并驱动机器：

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 很重要：创建机器的 agent 不应把它们留在系统里，这就是清理命令。