Skip to main content

​
vers rename

Rename a VM or cluster by setting a new alias.

​
Usage

vers rename                            # Rename current HEAD VM
vers rename [vm-id|alias]              # Rename specific VM
vers rename -c [cluster-id|alias]      # Rename cluster

​
Options

OptionDescription
--cluster, -cRename a cluster instead of a VM

​
Examples

​
Rename VMs

# Rename current HEAD VM
vers rename my-new-vm-name
Using current HEAD VM: vm-abc123
Renaming VM 'vm-abc123' to 'my-new-vm-name'...
✓ VM 'vm-abc123' renamed to 'my-new-vm-name'

# Rename specific VM by ID
vers rename vm-def456 production-server
Renaming VM 'vm-def456' to 'production-server'...
✓ VM 'vm-def456' renamed to 'production-server'

# Rename VM by existing alias
vers rename old-name new-name
Renaming VM 'old-name' to 'new-name'...
✓ VM 'vm-xyz789' renamed to 'new-name'

​
Rename clusters

# Rename cluster by ID
vers rename -c cluster-abc123 production-cluster
Renaming cluster 'cluster-abc123' to 'production-cluster'...
✓ Cluster 'cluster-abc123' renamed to 'production-cluster'

# Rename cluster by existing alias
vers rename -c old-cluster-name new-cluster-name
Renaming cluster 'old-cluster-name' to 'new-cluster-name'...
✓ Cluster 'cluster-def456' renamed to 'new-cluster-name'

​
How it works

The rename command:
  1. Argument parsing: Determines target and new alias based on argument count
    • 1 argument: Renames HEAD VM to the provided alias
    • 2 arguments: Renames specified target to new alias
  2. Target resolution: Resolves VM/cluster identifier to actual ID
  3. API update: Makes PATCH request to update the alias field
  4. Confirmation: Shows success message with old ID and new alias

​
Argument patterns

​
VM renaming

PatternTargetNew Alias
vers rename new-nameHEAD VMnew-name
vers rename vm-123 new-namevm-123new-name
vers rename old-alias new-nameVM with alias old-aliasnew-name

​
Cluster renaming

PatternTargetNew Alias
vers rename -c cluster-123 new-namecluster-123new-name
vers rename -c old-alias new-nameCluster with alias old-aliasnew-name

​
Error handling

​
Missing cluster ID

vers rename -c new-name
Error: cluster ID or alias must be provided when renaming clusters
Solution: Always provide both cluster identifier and new alias for cluster renames.

​
VM/Cluster not found

vers rename nonexistent-vm new-name
Error: failed to find VM: not found

vers rename -c nonexistent-cluster new-name
Error: failed to find cluster: not found

​
No HEAD VM

vers rename new-name
Error: no ID provided and HEAD not found
Solution: Run vers up to create a VM or specify a VM ID directly.

​
API failures

vers rename vm-123 new-name
Error: failed to rename VM 'vm-123': connection timeout

​
Use cases

​
Better organization

# Give VMs descriptive names
vers rename web-server
vers rename vm-def456 database-server
vers rename vm-ghi789 cache-server

​
Environment labeling

# Rename clusters for different environments
vers rename -c cluster-123 production
vers rename -c cluster-456 staging
vers rename -c cluster-789 development

​
Project organization

# Organize VMs by project
vers rename project-auth-api
vers rename vm-abc123 project-frontend
vers rename vm-def456 project-database

​
Prerequisites

  • VM/cluster must exist and be accessible
  • Network connectivity to perform the update
  • For VM renaming: Either provide VM ID or have a valid HEAD VM

​
See Also

  • vers status - View current VM and cluster names
  • vers tree - See VM relationships with aliases
  • vers up - Create VMs that can be renamed