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

Verification: The command verifies the target VM exists and is accessible
HEAD Update: Updates your local HEAD pointer to the target VM
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

Switch context by alias

vers checkout feature-branch
vers execute -- pwd   # now running on feature-branch

Move HEAD back to the parent after a branch

vers branch my-vm --vm-alias experiment --checkout
# ...explore experiment...
vers checkout my-vm   # back to the original

Combine with status for orientation

vers checkout staging-vm
vers status   # HEAD and fleet at a glance

Overview

Project Commands

Branch Commands

Repository Commands

VM Commands

Environment

Auth Commands

Utility Commands

Checkout

vers checkout

Synopsis

Description

Basic Usage

Show Current HEAD

Switch to VM by ID

Switch to VM by Alias

What Happens When You Checkout

Examples

Basic VM Switching

Using Aliases

Development Workflow

Error Scenarios

VM Not Found

No HEAD Set

Network/API Issues

Understanding HEAD

Tips

Common Patterns

Switch context by alias

Move HEAD back to the parent after a branch

Combine with status for orientation

See Also

​vers checkout

​Synopsis

​Description

​Basic Usage

​Show Current HEAD

​Switch to VM by ID

​Switch to VM by Alias

​What Happens When You Checkout

​Examples

​Basic VM Switching

​Using Aliases

​Development Workflow

​Error Scenarios

​VM Not Found

​No HEAD Set

​Network/API Issues

​Understanding HEAD

​Tips

​Common Patterns

​Switch context by alias

​Move HEAD back to the parent after a branch

​Combine with status for orientation

​See Also

vers checkout

Synopsis

Description

Basic Usage

Show Current HEAD

Switch to VM by ID

Switch to VM by Alias

What Happens When You Checkout

Examples

Basic VM Switching

Using Aliases

Development Workflow

Error Scenarios

VM Not Found

No HEAD Set

Network/API Issues

Understanding HEAD

Tips

Common Patterns

Switch context by alias

Move HEAD back to the parent after a branch

Combine with status for orientation

See Also