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.

Two small bits of ergonomics, but they show up everywhere. HEAD is the default target for most commands. Aliases are human-readable names you can use anywhere an id works. HEAD is a pointer to “the VM I’m working on right now.” Most commands default to HEAD when you don’t pass a VM id:
CommandDefault
vers connectConnect to HEAD
vers executeRun on HEAD
vers commitCommit HEAD
vers branchBranch from HEAD
vers pause / vers resumePause/resume HEAD
vers copyTransfer to/from HEAD
vers killDelete HEAD
HEAD is just a pointer, not a live connection. You can have HEAD pointing at one VM while your SSH session is connected to a different VM.

​
When HEAD moves

HEAD moves automatically when you:
  • run vers run → now points at the new root
  • run vers branch → now points at the new child
  • run vers run-commit → points at the new VM
  • run vers checkout <vm> → explicit move
  • delete the VM HEAD points at → HEAD is cleared

​
Inspecting HEAD

# Print the current HEAD VM id (scripting-friendly)
vers head

# Full status including HEAD
vers status

​
Where HEAD lives

.vers/HEAD inside your project directory. If you cd into a different project, you get a different HEAD. That’s the whole story — it’s literally a one-line file.
Outside a Vers project, HEAD is undefined and commands that default to it will fail with a clear error. Initialize a project with vers init or pass VM ids explicitly.

​
Aliases

Aliases are human-readable names for VM ids, stored locally. They make the difference between: 
vers connect vm-a1b2c3d4e5f6
and 
vers connect web-dev
They’re local only — they don’t sync between machines or teammates. Treat them as a typing shortcut, not a shared naming scheme. For names that need to travel, use tags and repos.

​
Creating aliases

When you create a VM: 
vers run --vm-alias web-dev
vers branch parent-vm --vm-alias feature-auth
vers run-commit <commit-id> --vm-alias restored
For an existing VM: 
vers alias set web-dev vm-a1b2c3d4

​
Using aliases

Aliases work anywhere a VM id works: 
vers connect web-dev
vers execute web-dev -- ls -la
vers checkout feature-auth
vers branch web-dev --vm-alias hotfix

​
Inspecting aliases

vers alias               # list all
vers alias web-dev       # show the id behind an alias

​
Where they live

~/.vers/aliases.json — a plain JSON map: 
{
  "web-dev": "vm-a1b2c3d4",
  "feature-auth": "vm-ef567890"
}
You can edit it by hand if you need to bulk-rename or migrate.

​
How HEAD and aliases work together

This is the ergonomics loop Vers wants you to fall into:
1

Name the VM when you create it

vers run --vm-alias dev
HEAD now points at dev.
2

Do work without typing the name

vers connect     # implicit HEAD
vers commit      # implicit HEAD
vers branch --vm-alias feature   # implicit HEAD as source
HEAD has moved to feature because vers branch sets HEAD.
3

Switch contexts without losing track

vers checkout dev       # HEAD back on the parent
vers checkout feature   # HEAD back on the branch
Named references, zero ids.

​
See also