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

# HEAD and aliases

> How commands know which VM you mean when you don't say — and how to name VMs so you never have to.

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

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:

| Command                      | Default               |
| ---------------------------- | --------------------- |
| `vers connect`               | Connect to HEAD       |
| `vers execute`               | Run on HEAD           |
| `vers commit`                | Commit HEAD           |
| `vers branch`                | Branch from HEAD      |
| `vers pause` / `vers resume` | Pause/resume HEAD     |
| `vers copy`                  | Transfer to/from HEAD |
| `vers kill`                  | Delete HEAD           |

<Warning>
  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.
</Warning>

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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.

<Tip>
  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`](/cli-reference/init) or pass VM ids explicitly.
</Tip>

## Aliases

Aliases are human-readable names for VM ids, stored locally. They make the difference between:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers connect vm-a1b2c3d4e5f6
```

and

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/concepts/commits#tagging-commits).

### Creating aliases

When you create a VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers alias set web-dev vm-a1b2c3d4
```

### Using aliases

Aliases work anywhere a VM id works:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers connect web-dev
vers execute web-dev -- ls -la
vers checkout feature-auth
vers branch web-dev --vm-alias hotfix
```

### Inspecting aliases

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers alias               # list all
vers alias web-dev       # show the id behind an alias
```

### Where they live

`~/.vers/aliases.json` — a plain JSON map:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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:

<Steps>
  <Step title="Name the VM when you create it">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    vers run --vm-alias dev
    ```

    HEAD now points at `dev`.
  </Step>

  <Step title="Do work without typing the name">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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.
  </Step>

  <Step title="Switch contexts without losing track">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    vers checkout dev       # HEAD back on the parent
    vers checkout feature   # HEAD back on the branch
    ```

    Named references, zero ids.
  </Step>
</Steps>

## See also

* [VMs](/concepts/vms) — what HEAD and aliases point at
* [vers checkout](/cli-reference/checkout), [vers alias](/cli-reference/alias), [vers head](/cli-reference/head)
* [vers status](/cli-reference/status) — HEAD at a glance