> ## 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.

# Checkout

# vers checkout

Switch your HEAD pointer to a different VM in your environment.

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout                        # Show current HEAD VM
vers checkout <vm-id>               # Switch to VM by ID
vers checkout <alias>               # Switch to VM by alias
```

## Description

The `checkout` command changes your current HEAD pointer to point to a different VM. HEAD determines which VM you'll interact with when using commands like `vers connect`, `vers execute`, or other VM-specific operations.

## Basic Usage

### Show Current HEAD

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout
```

Displays information about the VM your HEAD currently points to:

```
Current HEAD: vm-abc123 (State: Running)
```

If your VM has an alias, it will show the alias instead:

```
Current HEAD: my-app (State: Running)
```

### Switch to VM by ID

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout vm-abc123
```

Switches your HEAD to point to the specified VM ID.

### Switch to VM by Alias

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout my-app
```

Switches your HEAD to point to the VM with the specified alias.

## What Happens When You Checkout

1. **Verification**: The command verifies the target VM exists and is accessible
2. **HEAD Update**: Updates your local HEAD pointer to the target VM
3. **Confirmation**: Shows the switch was successful with VM state information

**Example output:**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout my-app
Verifying VM 'my-app'...
Switched to VM 'my-app' (State: Running)
```

## Examples

### Basic VM Switching

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check what VM you're currently on
vers checkout
Current HEAD: vm-abc123 (State: Running)

# Switch to different VM
vers checkout vm-def456
Verifying VM 'vm-def456'...
Switched to VM 'vm-def456' (State: Paused)
```

### Using Aliases

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Switch using alias name
vers checkout production-app
Verifying VM 'production-app'...
Switched to VM 'production-app' (State: Running)

# Check current HEAD shows alias
vers checkout
Current HEAD: production-app (State: Running)
```

### Development Workflow

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Start on your main VM
vers checkout main-vm

# Do some work, then switch to test environment
vers checkout test-env
Verifying VM 'test-env'...
Switched to VM 'test-env' (State: Running)

# Connect to the test environment
vers connect
# You're now connected to test-env VM

# Switch back to main when done
vers checkout main-vm
```

## Error Scenarios

### VM Not Found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout nonexistent-vm
Verifying VM 'nonexistent-vm'...
# Error: failed to switch to VM 'nonexistent-vm': VM not found
```

**Solution**: Check available VMs with `vers status`, or verify the VM ID/alias is correct.

### No HEAD Set

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout
# Error: failed to get current HEAD: no HEAD set
```

**Solution**: Switch to a VM first, or run `vers status` to see available VMs.

### Network/API Issues

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout vm-abc123
Verifying VM 'vm-abc123'...
# Error: failed to switch to VM 'vm-abc123': context deadline exceeded
```

**Solution**: Check your network connection and try again. The command has a 10-second timeout for VM verification.

## Understanding HEAD

HEAD is a pointer that tracks which VM you're currently "on". When you run VM-specific commands, they operate on whatever VM HEAD points to:

* **`vers connect`** - Connects to HEAD VM
* **`vers execute`** - Runs commands on HEAD VM
* **`vers branch`** - Creates new VM from HEAD VM (if no VM specified)

Think of HEAD as your "current working VM" - similar to how git has a current working branch.

## Tips

* Always run `vers checkout` to see your current VM before running other commands
* Use meaningful aliases for your VMs to make switching easier
* VM aliases are more memorable than VM IDs (e.g., `production-app` vs `vm-a1b2c3d4`)
* If you're unsure what VMs are available, use `vers status`

## Common Patterns

### Switch context by alias

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout feature-branch
vers execute -- pwd   # now running on feature-branch
```

### Move HEAD back to the parent after a branch

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers branch my-vm --vm-alias experiment --checkout
# ...explore experiment...
vers checkout my-vm   # back to the original
```

### Combine with status for orientation

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers checkout staging-vm
vers status   # HEAD and fleet at a glance
```

## See Also

* [vers status](status) - See all available VMs and current HEAD
* [vers connect](connect) - Connect to your current HEAD VM
* [vers branch](branch) - Create new VM from current HEAD