آٹومیشن اور JSON

ہر command --json لیتا ہے اور stdout پر machine-readable output دیتا ہے، errors stderr پر اور معنی خیز exit code کے ساتھ۔ shapes منجمد ہیں: ہر object میں apiVersion: 1 ہوتا ہے، fields صرف شامل ہوتے ہیں، اور breaking change version بڑھاتا ہے۔ test suite انہیں lock کرتی ہے۔

Output 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

تباہ کن commands prompt کی بجائے exit 4 سے انکار کرتی ہیں۔ interactive prompts نہیں ہیں، اس لیے script کبھی انسان کا انتظار نہیں کرتی۔ جب آپ کا ارادہ ہو تو --force یا --yes دیں۔

ایک قابلِ اعتماد script

غلطی یہ ہے کہ "running" کو "ready" سمجھ لیا جائے۔ wait-ready اس وقت تک بلاک کرتا ہے جب تک guest واقعی 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

ایک command میں disposable machines

task run پورا clone-wait-exec-dispose loop آپ کے لیے کرتا ہے:

1vm task run -- ./build.sh

یہ pinned golden image clone کرتا ہے، readiness کا انتظار کرتا ہے، 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 اہم ہے: جو agent machines بناتا ہے وہ انہیں ادھر ادھر نہیں چھوڑنا چاہیے، اور یہ cleanup verb ہے۔