Skip to main content

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.

​
vers checkout

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

​
Synopsis

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

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

vers checkout vm-abc123
Switches your HEAD to point to the specified VM ID.

​
Switch to VM by Alias

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: 
vers checkout my-app
Verifying VM 'my-app'...
Switched to VM 'my-app' (State: Running)

​
Examples

​
Basic VM Switching

# 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

# 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

# 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

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

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

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

​
Quick Status Check

# See what VM you're on
vers checkout
Current HEAD: my-dev-env (State: Running)

​
Environment Switching

# Switch between development environments
vers checkout dev-env
vers checkout staging-env  
vers checkout prod-env

​
Working with VM IDs

# When you only have VM ID
vers checkout vm-1a2b3c4d5e

# After switching, see if it has an alias
vers checkout
Current HEAD: vm-1a2b3c4d5e (State: Running)

​
See Also