> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Status

# vers status

Get status of VMs.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status                          # Show all VMs status
vers status [vm-id|alias]            # Show specific VM information
```

## Examples

### Show all VMs (default)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status
HEAD status: vm-abc123 (State: Running)

Fetching list of VMs...
Available VMs:

VM: web-server
State: Running

VM: vm-def456
State: Paused

VM: feature-auth
State: Running
```

### Show specific VM details

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status vm-abc123
Getting status for VM: web-server

VM details:
VM: web-server
State: Running
```

## How it works

The `status` command has two modes:

### Default mode (no arguments)

1. **Shows HEAD status**: Displays current HEAD VM and its state
2. **Lists all VMs**: Shows VM names and their states

### VM mode (VM argument)

1. **Resolves VM**: Finds VM by ID or alias
2. **Shows VM details**: Displays VM name and state

## HEAD status variations

### Normal HEAD with running VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
HEAD status: vm-abc123 (State: Running)
```

### HEAD with VM alias

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
HEAD status: web-server (State: Paused)
```

### No .vers repository

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
HEAD status: Not a vers repository (run 'vers init' first)
```

### Empty HEAD

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
HEAD status: Empty (create a VM with 'vers run')
```

### HEAD verification failed

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
HEAD status: vm-abc123 (unable to verify)
```

## Output format

### VM list format

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

## Error handling

### VM not found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status nonexistent-vm
Error: failed to find VM 'nonexistent-vm': not found
```

### No VMs exist

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status
HEAD status: Empty (create a VM with 'vers run')

Fetching list of VMs...
No VMs found.
```

### API failures

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers status
Error: failed to list VMs: connection timeout
```

## Use cases

### Environment overview

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check what's available
vers status

# Check specific VM
vers status my-vm
```

### VM monitoring

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check specific VM state
vers status my-web-server
```

### Debugging

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check HEAD status
vers status

# Verify specific VM
vers status problematic-vm
```

## Prerequisites

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

## Common Patterns

### Wait for a VM to reach Running

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
while [ "$(vers status my-vm --format json | jq -r .state)" != "Running" ]; do
  sleep 1
done
echo "my-vm is up"
```

### Pipe into other commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Kill every VM
vers kill -y $(vers status -q)

# Count running VMs
vers status --format json | jq '[.[] | select(.state == "Running")] | length'
```

### Watch fleet state in a loop

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
watch -n 2 'vers status'
```

## See Also

* [vers connect](/cli-reference/connect) - Connect to running VMs
* [vers run](/cli-reference/run) - Create VMs when none exist