Skip to main content

​
vers status

Displays the status of all clusters by default. Use -c flag for specific cluster details, or provide a VM ID or alias as argument for VM-specific status.

​
Usage

vers status                          # Show HEAD status and all clusters
vers status -c [cluster-id|alias]    # Show detailed cluster information
vers status [vm-id|alias]            # Show specific VM information

​
Options

OptionDescription
--cluster, -cCluster ID or alias to show detailed status for

​
Examples

​
Show all clusters (default)

vers status
HEAD status: vm-abc123 (State: Running)

Fetching list of clusters...
Available clusters:

Cluster: production
Root VM: web-server
# children: 3

Cluster: development
Root VM: vm-def456
# children: 5

Tip: To view VMs in a specific cluster, use: vers status -c 
To view a specific VM, use: vers status

​
Show specific cluster details

vers status -c development
Getting status for cluster: development

Cluster details:
Cluster: development
Root VM: vm-def456
# VMs: 5

VMs in this cluster:
VM: vm-def456
State: Running

VM: feature-auth
State: Paused

VM: vm-ghi789
State: Running

Tip: To view all clusters, run: vers status

​
Show specific VM details

vers status vm-abc123
Getting status for VM: web-server

VM details:
VM: web-server
State: Running
Cluster: cluster-xyz789

Tip: To view the cluster containing this VM, run: vers status -c cluster-xyz789

​
How it works

The status command has three modes:

​
Default mode (no arguments)

  1. Shows HEAD status: Displays current HEAD VM and its state
  2. Lists all clusters: Shows cluster names, root VMs, and VM counts
  3. Provides navigation tips: Suggests next commands to explore

​
Cluster mode (-c flag)

  1. Resolves cluster: Finds cluster by ID or alias
  2. Shows cluster details: Displays cluster info and VM count
  3. Lists all VMs: Shows each VM’s name and state

​
VM mode (VM argument)

  1. Resolves VM: Finds VM by ID or alias
  2. Shows VM details: Displays VM name, state, and cluster
  3. Provides cluster tip: Suggests viewing the containing cluster

​
HEAD status variations

​
Normal HEAD with running VM

HEAD status: vm-abc123 (State: Running)

​
HEAD with VM alias

HEAD status: web-server (State: Paused)

​
No .vers repository

HEAD status: Not a vers repository (run 'vers init' first)

​
Empty HEAD

HEAD status: Empty (create a VM with 'vers run')

​
HEAD verification failed

HEAD status: vm-abc123 (unable to verify)

​
Output format

​
Cluster list format

  • Cluster name: Shows alias if available, otherwise cluster ID
  • Root VM: Shows VM alias if available, otherwise VM ID
  • VM count: Total number of VMs in the cluster

​
VM list format

  • VM name: Shows alias if available, otherwise VM ID
  • State: Current VM state (Running, Paused, Stopped, etc.)

​
Error handling

​
Cluster not found

vers status -c nonexistent-cluster
Error: failed to find cluster 'nonexistent-cluster': not found

​
VM not found

vers status nonexistent-vm
Error: failed to find VM 'nonexistent-vm': not found

​
No clusters exist

vers status
HEAD status: Empty (create a VM with 'vers run')

Fetching list of clusters...
No clusters found.

​
API failures

vers status
Error: failed to list clusters: connection timeout

​
Use cases

​
Environment overview

# Check what's available
vers status

# Pick a cluster to examine
vers status -c interesting-cluster

​
VM monitoring

# Check specific VM state
vers status my-web-server

# Check cluster containing that VM
vers status -c production

# See all clusters
vers status

# Drill down into one
vers status -c development

# Check individual VMs
vers status feature-vm

​
Debugging

# Check HEAD status
vers status

# Verify specific VM
vers status problematic-vm

# Check its cluster
vers status -c cluster-with-issues

​
Prerequisites

  • For cluster/VM details: Network connectivity to query API
  • For HEAD status: .vers directory (optional, shows warning if missing)

​
See Also