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 alias

Show VM ID for an alias, or list all aliases.

​
Synopsis

vers alias              # List all aliases
vers alias <name>       # Show VM ID for specific alias

​
Description

The alias command lets you look up VM IDs from their human-readable aliases, or view all defined aliases. Aliases are stored locally on your machine and provide a convenient way to reference VMs without remembering their full IDs.

​
Usage

​
List All Aliases

vers alias
Output: 
web-server -> vm-abc123def456
database -> vm-789xyz012345
test-env -> vm-qwerty098765

​
Look Up Specific Alias

vers alias web-server
Output: 
vm-abc123def456

​
How Aliases Work

Aliases are a local convenience feature - they’re stored on your machine, not on the server.

​
Storage Location

Aliases are saved in ~/.vers/aliases.json: 
{
  "web-server": "vm-abc123def456",
  "database": "vm-789xyz012345"
}

​
Setting Aliases

Aliases are created when you use the --alias or --vm-alias flags: 
# When starting a new environment
vers run --vm-alias my-dev-env

# When branching
vers branch --alias feature-test

# When restoring from a commit
vers run-commit c123456 --vm-alias restored-env

​
Using Aliases

Once set, aliases work anywhere you’d use a VM ID: 
vers connect my-dev-env      # Instead of: vers connect vm-abc123
vers checkout my-dev-env     # Instead of: vers checkout vm-abc123
vers execute my-dev-env "ls" # Instead of: vers execute vm-abc123 "ls"
vers status my-dev-env       # Instead of: vers status vm-abc123
vers kill my-dev-env         # Instead of: vers kill vm-abc123
vers copy my-dev-env:/path . # Instead of: vers copy vm-abc123:/path .

​
Examples

​
Development Workflow

# Create environment with alias
vers run --vm-alias dev

# Work with it using the alias
vers connect dev
# ... do work ...
exit

# Branch with a new alias
vers branch --alias feature-x

# Switch between them easily
vers checkout dev
vers checkout feature-x

# Check your aliases
vers alias
# Output:
# dev -> vm-abc123
# feature-x -> vm-def456

​
Scripting

# Get VM ID for use in scripts
VM_ID=$(vers alias my-env)
echo "Working with VM: $VM_ID"

​
Error Handling

​
Alias Not Found

vers alias nonexistent
# Error: alias 'nonexistent' not found

​
No Aliases Defined

vers alias
# No aliases defined.

​
Notes

  • Aliases are local only - they don’t sync across machines
  • Aliases persist until the VM is deleted or you manually edit ~/.vers/aliases.json
  • If a VM is deleted, its alias becomes stale (pointing to a non-existent VM)
  • Alias names can contain letters, numbers, hyphens, and underscores

​
See Also