CLI reference

Last updated: 2026-06-27

Which command do I want?

I want to…	Use
Run something once and throw it away	run
Keep a workspace around between boots	create, then start
Get a shell inside a workspace	connect
Run a command inside and get its exit code	exec
Copy files in or out	cp
See saved workspaces	list or ls
See what’s running	ps
Dig into one workspace	status
See what the VM printed at boot	logs
Get the structured result of a run	result
Park it / shut it down / force it	halt / stop / kill
Freeze it in place, memory and all	pause / resume
Checkpoint or fork it	snapshot, clone
Get rid of it	delete
Figure out why nothing boots	doctor

All commands

Command	Purpose
init	Scaffold a starter agent project
run	Boot an image and run a command, then tear down
create	Create a named, persistent workspace
apply	Apply supported workspace spec changes without rebuilding
clone	Copy a stopped workspace into a new workspace
commit	Snapshot a stopped workspace rootfs into an OCI image
cp	Copy files into or out of stopped workspace disks
artifact	List and retrieve declared workspace artifacts
network	Inspect declared network intent and runtime network state
model	Download and manage local HuggingFace GGUF model files
volume	Manage named volumes - VM-independent ext4 disks attached by name
start	Boot a stopped workspace
supervise	Start and restart a workspace according to policy
halt	Clean disk-preserving shutdown
quarantine	Sever host-side network and mediation
pause	Freeze a running workspace’s vCPUs, preserving memory and disk
resume	Thaw a paused workspace back to running
stop	Graceful shutdown
kill	Hard terminate
delete	Remove a workspace and its state
status	Show workspace state
result	Show structured workspace result
list	List saved workspaces (ls alias)
ps	List running workspaces
logs	Show boot/serial output
events	Show or stream the lifecycle event history
egress	Show or stream the egress mediator’s audit decisions
stats	Show or stream workspace resource usage
snapshot	Create, list, or remove workspace snapshots
secret	Resolve and validate secret references
connect	Open the workspace console
exec	Run a structured command in a workspace
profiles	List exact named resource profiles
image	Manage local image records
perf	Measure workspace boot performance
serve	Run the MCP stdio server for agent clients
contract	Print the runtime fields integrations rely on
host	Report host backend capabilities
doctor	Check the host for backend support
rootfs	Build a rootfs from an OCI image
kernel	Install or verify a custom kernel
version	Print the version

Container-style convenience

microagent run accepts both the explicit --image IMAGE --exec "cmd" form and the shorter microagent run IMAGE [COMMAND ARG...] form. For flags that map cleanly onto a microVM, common aliases are available: -e for --env, -p for --publish, -v/--volume for named volumes, tar bundles, and ext4 disk images, --name, and --rm.

Some Docker-style inputs do not map to a microVM boundary - privileged mode, namespace flags, devices, and host directory bind mounts. When microagent run recognizes one of these, it returns targeted guidance rather than silently changing its meaning.

Workspace spec

microagent.yaml is the declarative form of microagent create - image, profile, restart policy, networking, mounts, mediation, and outputs in a single file you can keep in source control.

Global flags

These flags are recognized before the subcommand and apply across commands that produce output. Subcommand pages link back here rather than repeat them.

• --json - print structured JSON output; place before the subcommand
• --text - print human-readable output
• --output <json|text> - select output format
• --mode <ux|ax> - select the output mode. ux is the default human-oriented mode; ax is the agent mode, which forces JSON output and emits structured error envelopes on failure. MICROAGENT_MODE sets the same value (ux/human/text map to UX; ax/agent/json map to AX). --mode ax implies --json; when neither is set, MICROAGENT_OUTPUT=json|text selects the format and output otherwise follows whether stdout is a terminal.
• --supervisor <path> - override the installed host backend supervisor path (MICROAGENT_APPLEVF_SUPERVISOR and MICROAGENT_FIRECRACKER_SUPERVISOR work too)

Output

All commands can print JSON output. With --json before the subcommand (or MICROAGENT_OUTPUT=json), the response uses the same structured result shape the Go library and MCP adapter use. Scripts should consume JSON; humans get the text format by default.