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

# Run commit

# vers run-commit

Start a Vers development environment from an existing commit, or from a repository tag reference.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit <commit-key>                     # by commit ID (UUID)
vers run-commit <repo>:<tag>                     # by repo:tag reference (org-local)
vers run-commit <org>/<repo>:<tag>               # by public repo reference (cross-org)
vers run-commit <org>/<repo>                     # shorthand for <org>/<repo>:latest
vers run-commit <commit-key> --vm-alias web-server
vers run-commit my-app:latest --wait
```

## Options

| Option           | Description                   |
| ---------------- | ----------------------------- |
| `--vm-alias, -N` | Set an alias for the root VM  |
| `--wait`         | Block until the VM is running |
| `--format`       | Output format: `json`         |

## Examples

### Start from commit key

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit c123456789abcdef
Sending request to start environment from commit c123456789abcdef...
Environment started successfully from commit c123456789abcdef with root vm 'vm-abc123'.
HEAD now points to: vm-abc123 (from commit c123456789abcdef)
```

### With custom alias

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit c123456789abcdef --vm-alias web-server
Sending request to start environment from commit c123456789abcdef...
Environment started successfully from commit c123456789abcdef with root vm 'vm-abc123'.
HEAD now points to: web-server (from commit c123456789abcdef)
```

### Start from a repo:tag reference

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit my-app:latest --vm-alias dev
Sending request to start VM from commit my-app:latest...
VM 'vm-abc123' started successfully from commit my-app:latest.
HEAD now points to: dev (from commit my-app:latest)
```

The argument format is auto-detected: UUIDs are treated as commit IDs, and anything containing `:` is treated as a repository reference. The server resolves org-local repos first, then falls back to cross-org public repos when the reference contains a `/`. This means org-local repos whose names contain slashes (e.g. `team/project:v1`) always take priority over cross-org references.

### Start from a public repo

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit acme/ubuntu:latest --vm-alias my-env

# equivalent shorthand (defaults to :latest)
vers run-commit acme/ubuntu --vm-alias my-env
```

This resolves the tag from acme's public repository. The repo must have been made public with `vers repo visibility <name> --public`.

<Note>
  The `org/repo:tag` form only resolves **public** repos cross-org. To reference your own private repo, use the bare form `repo:tag` (without the org prefix).
</Note>

## How it works

The `run-commit` command:

1. **Validates commit key**: Ensures the commit key is provided
2. **Creates environment**: Makes API call to create environment from the specified commit
3. **Updates HEAD**: Sets your local HEAD to point to the new root VM
4. **Confirms success**: Shows environment and root VM information

## What gets created

* **New environment**: Created from the commit's state
* **Root VM**: The primary VM, restored from commit
* **Local HEAD**: Updated to point to the new root VM

## Getting commit keys

### From creating commits

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers commit
Commit created successfully
Commit ID: c234567890abcdef

# Later, recreate this exact state
vers run-commit c234567890abcdef
```

### From team members

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Team member shares their commit key
vers run-commit c345678901abcdef  # Exact same environment state
```

## Error handling

### Invalid commit key

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit invalid-commit-key
Error: failed to start environment: commit not found
```

### Missing commit key

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit
Error: accepts 1 arg(s), received 0
```

### No .vers directory

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run-commit c123456789abcdef
Environment started successfully...
Warning: .vers directory not found. Run 'vers init' first.
```

**Solution**: Run `vers init` in your project directory first.

## Use cases

### Reproduce specific state

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Start environment from a known good commit
vers run-commit c123456789abcdef
vers connect
# Environment is exactly as it was at commit time
```

### Team collaboration

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Team member shares commit key
vers run-commit c234567890abcdef
# Now you have the exact same environment state
```

### Testing and debugging

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Start from specific commit
vers run-commit c345678901abcdef
vers connect
# Debug in the exact environment where issue occurred
```

### CI/CD integration

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Use commit key from automated commits
vers run-commit $COMMIT_KEY --vm-alias ci-test-$BUILD_ID
# Run tests in reproduced environment
```

## Prerequisites

* Valid commit key from an accessible commit
* Authenticated with Vers platform
* Network connectivity
* Project directory (`.vers` directory recommended)

## Notes

* Aliases set with `--vm-alias` are stored locally at `~/.vers/aliases.json`
* Use `vers alias` to view all your aliases

## Common Patterns

### Boot the latest tagged commit

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# From a plain tag
vers run-commit production --vm-alias prod-hotfix

# From a repo tag
vers run-commit my-app:latest --vm-alias staging
```

### Boot a commit for debugging, then throw away

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM=$(vers run-commit "$INCIDENT_COMMIT" --wait --format json | jq -r .root_vm_id)
vers execute "$VM" -- journalctl --no-pager -u my-service -n 200
vers kill -y "$VM"
```

### Pin infra in CI

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# CI job: boot the exact commit that was green in last week's smoke test
vers run-commit "$KNOWN_GOOD_COMMIT" --wait
```

## See Also

* [vers alias](/cli-reference/alias) - View and look up aliases
* [vers run](/cli-reference/run) - Start fresh development environment
* [vers commit](/cli-reference/commit) - Create commits for later reproduction