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

# Alias

# vers alias

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

## Synopsis

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

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

Output:

```
web-server -> vm-abc123def456
database -> vm-789xyz012345
test-env -> vm-qwerty098765
```

### Look Up Specific Alias

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "web-server": "vm-abc123def456",
  "database": "vm-789xyz012345"
}
```

### Setting Aliases

Aliases are created when you use the `--alias` or `--vm-alias` flags:

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Get VM ID for use in scripts
VM_ID=$(vers alias my-env)
echo "Working with VM: $VM_ID"
```

## Error Handling

### Alias Not Found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers alias nonexistent
# Error: alias 'nonexistent' not found
```

### No Aliases Defined

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

## Common Patterns

### Name a long-running VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --vm-alias dev-main
# ...later, from anywhere...
vers connect dev-main
```

### Re-alias an existing VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers alias set my-app vm-abc123
```

### Resolve an alias to the underlying ID

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM_ID=$(vers alias lookup my-app)
```

## See Also

* [vers run](run) - Start environment with `--vm-alias`
* [vers branch](branch) - Create branch with `--alias`
* [vers run-commit](run-commit) - Restore from commit with `--vm-alias`
* [vers checkout](checkout) - Switch HEAD using alias