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

> Print the VM ID that HEAD currently points to. The scripting primitive behind most other commands.

`vers head` prints the VM ID that `HEAD` currently points to. It's the scripting primitive behind the default target for most other commands — when you run `vers status` or `vers commit` without an argument, HEAD is what they resolve to.

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers head
```

Prints the HEAD VM ID to stdout, or fails with a non-zero exit code if there is no HEAD.

## Examples

### Use HEAD in a script

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM=$(vers head)
echo "Working on $VM"
vers execute "$VM" -- uptime
```

### Chain with other commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Info for HEAD
vers info $(vers head)

# Kill HEAD explicitly
vers kill $(vers head)
```

<Tip>
  Most commands already default to HEAD when no VM is given. Use `vers head` when you need the ID as a value — in a variable, a label, or a pipeline into a non-Vers tool.
</Tip>

## How HEAD works

HEAD is a per-project pointer stored in `.vers/HEAD`. It moves automatically when you:

* run `vers run` (points at the new root VM)
* run `vers branch` (points at the new branch)
* run `vers checkout <vm>` (explicit move)
* delete the HEAD VM (cleared)

If you're not inside a Vers project directory, or HEAD hasn't been set, the command fails.

## Common Patterns

### Check whether you're in a Vers project

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
if vers head >/dev/null 2>&1; then
  echo "HEAD is $(vers head)"
else
  echo "not in a Vers project, or HEAD not set"
fi
```

### Use HEAD in your shell prompt

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# in ~/.bashrc / ~/.zshrc
PS1='[vers:$(vers head 2>/dev/null || echo "-")] \w $ '
```

### Pipe into any VM-taking command

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers info $(vers head)
vers execute $(vers head) -- uptime
ssh $(vers head).vm.vers.sh
```

## See also

* [vers checkout](/cli-reference/checkout) — move HEAD to a different VM
* [vers status](/cli-reference/status) — HEAD state plus VM list
* [vers alias](/cli-reference/alias) — human-readable names for VM IDs