Skip to main content

​
vers run-commit

Start a Vers development environment from an existing commit using its commit ID.

​
Usage

vers run-commit [commit-id]

​
Options

OptionDescription
--fs-size-clusterOverride cluster filesystem size (MiB)
--cluster-alias, -nSet an alias for the cluster
--vm-alias, -NSet an alias for the root VM

​
Examples

​
Start from commit ID

vers run-commit c123456789abcdef
Sending request to start cluster from commit c123456789abcdef...
Cluster (ID: cluster-xyz789) started successfully from commit c123456789abcdef with root vm 'vm-abc123'.
HEAD now points to: vm-abc123 (from commit c123456789abcdef)

​
With custom aliases

vers run-commit c123456789abcdef --cluster-alias production --vm-alias web-server
Sending request to start cluster from commit c123456789abcdef...
Cluster (ID: cluster-xyz789) started successfully from commit c123456789abcdef with root vm 'vm-abc123'.
HEAD now points to: web-server (from commit c123456789abcdef)

​
With configuration overrides

vers run-commit c123456789abcdef --fs-size-cluster 2048 --cluster-alias large-env
Sending request to start cluster from commit c123456789abcdef...
Cluster (ID: cluster-xyz789) started successfully from commit c123456789abcdef with root vm 'vm-abc123'.
HEAD now points to: vm-abc123 (from commit c123456789abcdef)

​
How it works

The run-commit command:
  1. Loads configuration: Reads vers.toml for default settings
  2. Applies overrides: Uses command-line flags to override configuration
  3. Creates cluster: Makes API call to create cluster from the specified commit ID
  4. Updates HEAD: Sets your local HEAD to point to the new root VM
  5. Confirms success: Shows cluster ID and root VM information

​
What gets created

  • New cluster: Created from the commit’s state
  • Root VM: The primary VM in the cluster, restored from commit
  • Local HEAD: Updated to point to the new root VM

​
Getting commit IDs

​
From commit history

vers history
Commit History for VM: my-web-server

Commit: c123456789abcdef
Author: [email protected]
Date: Mon Jan 15 14:30:25 2024 -0700
VM: vm-abc123

    Add authentication feature

# Use the commit ID with run-commit
vers run-commit c123456789abcdef

​
From creating commits

vers commit -m "Working authentication system"
Commit created successfully
Commit ID: c234567890abcdef

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

​
From team members

# Team member shares their commit ID
vers run-commit c345678901abcdef  # Exact same environment state

​
Configuration integration

The command respects your vers.toml configuration: 
[machine]
fs_size_cluster_mib = 1024  # Used unless overridden by --fs-size-cluster
Command-line flags take precedence over configuration file values.

​
Error handling

​
Invalid commit ID

vers run-commit invalid-commit-id
Error: failed to start cluster: commit not found

​
Missing commit ID

vers run-commit
Error: accepts 1 arg(s), received 0

​
No .vers directory

vers run-commit c123456789abcdef
Cluster (ID: cluster-xyz789) started successfully...
Warning: .vers directory not found. Run 'vers init' first.
Solution: Run vers init in your project directory first.

​
API failures

vers run-commit c123456789abcdef
Error: connection timeout

​
Use cases

​
Reproduce specific state

# Check available commits
vers history

# Start environment from a known good commit
vers run-commit c123456789abcdef
vers connect
# Environment is exactly as it was at commit time

​
Team collaboration

# Team member shares commit ID from their history
vers run-commit c234567890abcdef
# Now you have the exact same environment state

​
Testing and debugging

# Find commit where bug was reported
vers history

# Start from that specific commit
vers run-commit c345678901abcdef
vers connect
# Debug in the exact environment where issue occurred

​
CI/CD integration

# Use commit ID from automated commits
vers run-commit $COMMIT_ID --cluster-alias ci-test-$BUILD_ID
# Run tests in reproduced environment

​
Prerequisites

  • Valid commit ID from an accessible commit
  • Authenticated with Vers platform
  • Network connectivity
  • Sufficient resources to create the cluster
  • Project directory (.vers directory recommended)

​
See Also