Skip to main content

​
Synopsis

smolvm list [OPTIONS]

​
Description

The list command shows you which VMs are currently running on your system. By default it displays only running VMs in a formatted table. You can also filter by status or get machine-readable JSON output for use in scripts.

​
Options

​
--all
flag
default:"false"
Include all VMs regardless of status (running, stopped, created, and error states).
​
--status
string
Filter VMs by a specific status. Choices: created, running, stopped, error. Cannot be used together with --all.
​
--json
flag
default:"false"
Print VM data as JSON instead of a formatted table. Useful for scripting and automation.
The --all and --status flags are mutually exclusive. Use one or the other, not both.

​
Examples

​
List running VMs

Show all currently running VMs in a table: 
smolvm list
Example output: 
        SmolVM Instances
┌──────────────┬─────────┬───────┐
│ Name         │ Status  │   PID │
├──────────────┼─────────┼───────┤
│ my-agent     │ running │ 12345 │
│ dev-sandbox  │ running │ 12400 │
└──────────────┴─────────┴───────┘
Total: 2 VM(s).

​
List all VMs

Include VMs in any state — running, stopped, created, or error: 
smolvm list --all
Example output: 
           SmolVM Instances
┌──────────────┬─────────┬───────┐
│ Name         │ Status  │   PID │
├──────────────┼─────────┼───────┤
│ my-agent     │ running │ 12345 │
│ dev-sandbox  │ running │ 12400 │
│ old-vm       │ stopped │     - │
│ broken-vm    │ error   │     - │
└──────────────┴─────────┴───────┘
Total: 4 VM(s).

​
Filter by status

Show only stopped VMs: 
smolvm list --status stopped

​
JSON output

Get machine-readable output for scripting: 
smolvm list --all --json
Example output: 
[
  {
    "vm_id": "my-agent",
    "status": "running",
    "ip_address": "172.16.0.2",
    "ssh_port": 2222,
    "pid": 12345
  },
  {
    "vm_id": "dev-sandbox",
    "status": "running",
    "ip_address": "172.16.0.3",
    "ssh_port": 2223,
    "pid": 12400
  }
]

​
Use with other tools

Combine JSON output with tools like jq for automation: 
# Get IDs of all running VMs
smolvm list --json | jq -r '.[].vm_id'

# Count VMs by status
smolvm list --all --json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

​
Table columns

The default table output shows the following columns:
ColumnDescription
NameThe VM identifier
StatusCurrent VM state (created, running, stopped, error)
PIDProcess ID of the VM process, or - if not running
The JSON output includes additional fields: ip_address (guest IP) and ssh_port (SSH host port).

​
Exit codes

CodeDescription
0Success
1Error listing VMs
Last modified on March 29, 2026