Skip to main content

​
vers run-commit

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

​
Usage

vers run-commit <commit-key>                     # by commit ID (UUID)
vers run-commit <repo>:<tag> --ref               # by repo:tag reference
vers run-commit <commit-key> --vm-alias web-server
vers run-commit my-app:latest --ref --wait

​
Options

OptionDescription
--refInterpret the argument as a repo:tag reference instead of a commit ID. The API resolves the tag within your own org.
--vm-alias, -NSet an alias for the root VM
--waitBlock until the VM is running
--formatOutput format: json

​
Examples

​
Start from commit key

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

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

vers run-commit my-app:latest --ref --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 --ref flag changes the API payload from {"commit_id": "..."} to {"ref": "..."}. The server resolves the ref against tags owned by your org.
Without --ref, an argument that contains a : will be rejected early with a hint to add the flag. Sending my-app:latest as commit_id would otherwise fail with a 422 from the server, because it isn’t a valid UUID.
Cross-org references (org/repo:tag) are not accepted by from_commit/run-commit. To consume another org’s public repo, use vers repo fork first.

​
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

vers commit
Commit created successfully
Commit ID: c234567890abcdef

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

​
From team members

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

​
Error handling

​
Invalid commit key

vers run-commit invalid-commit-key
Error: failed to start environment: commit not found

​
Missing commit key

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

​
No .vers directory

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

# 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 key
vers run-commit c234567890abcdef
# Now you have the exact same environment state

​
Testing and debugging

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

​
CI/CD integration

# 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

# 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

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

# CI job: boot the exact commit that was green in last week's smoke test
vers run-commit "$KNOWN_GOOD_COMMIT" --wait

​
See Also