diff --git a/cli/cmd/vm_create.go b/cli/cmd/vm_create.go
index f02a3d6fd..b1ad24ad1 100644
--- a/cli/cmd/vm_create.go
+++ b/cli/cmd/vm_create.go
@@ -39,20 +39,28 @@ By default, the command provisions one VM, but you can customize the number of V
 The command also supports a "--wait" flag to wait for the VMs to be ready before returning control, with a customizable timeout duration.
 
 VMs are currently a beta feature.`,
-		Example: `# Create a single Ubuntu 20.04 VM
-replicated vm create --distribution ubuntu --version 20.04
+		Example: `# Create a single Ubuntu 22.04 VM
+replicated vm create --distribution ubuntu --version 22.04
 
 # Create 3 Ubuntu 22.04 VMs
 replicated vm create --distribution ubuntu --version 22.04 --count 3
 
 # Create 5 Ubuntu VMs with a custom instance type and disk size
-replicated vm create --distribution ubuntu --version 20.04 --count 5 --instance-type r1.medium --disk 100
+replicated vm create --distribution ubuntu --version 22.04 --count 5 --instance-type r1.medium --disk 100
 
 # Create a VM with an SSH public key
-replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub
+replicated vm create --distribution ubuntu --version 22.04 --ssh-public-key ~/.ssh/id_rsa.pub
 
 # Create a VM with multiple SSH public keys
-replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub`,
+replicated vm create --distribution ubuntu --version 22.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub
+
+# Create a VM with an SSH public key, then SSH in.
+# The Linux user provisioned on the VM is taken from the part of the key's
+# comment before the first '@'. A key with comment "ci@host" creates user "ci",
+# so pass --username to vm ssh-endpoint to connect as that user.
+ssh-keygen -t ed25519 -C ci@host -f /tmp/ci_key -N ""
+replicated vm create --distribution ubuntu --ssh-public-key /tmp/ci_key.pub --name my-vm --wait 5m
+ssh -i /tmp/ci_key $(replicated vm ssh-endpoint my-vm --username ci)`,
 		SilenceUsage: true,
 		RunE:         r.createVM,
 		Args:         cobra.NoArgs,
@@ -73,7 +81,7 @@ replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.s
 	cmd.Flags().StringVar(&r.args.createVMNetwork, "network", "", "The network to use for the VM(s). If not supplied, create a new network")
 
 	cmd.Flags().StringArrayVar(&r.args.createVMTags, "tag", []string{}, "Tag to apply to the VM (key=value format, can be specified multiple times)")
-	cmd.Flags().StringArrayVar(&r.args.createVMPublicKeys, "ssh-public-key", []string{}, "Path to SSH public key file to add to the VM (can be specified multiple times)")
+	cmd.Flags().StringArrayVar(&r.args.createVMPublicKeys, "ssh-public-key", []string{}, "Path to SSH public key file to add to the VM (can be specified multiple times). The Linux user that receives the key is derived from the key's comment: the portion before the first '@'. For example, a comment of 'runner@host' creates a user named 'runner'; pass that name via 'replicated vm ssh-endpoint --username runner' to connect.")
 	cmd.Flags().StringVar(&r.args.createVMRBACPolicyName, "rbac-policy-name", "", "(alpha) Name of the RBAC policy to assign to the VM (enables automatic vendor-api authentication inside the VM)")
 	cmd.Flags().MarkHidden("rbac-policy-name")
 	cmd.Flags().BoolVar(&r.args.createVMOverlayFS, "overlayfs", false, "(alpha) Use overlayfs-backed rootfs management for the VM")
diff --git a/cli/cmd/vm_endpoints.go b/cli/cmd/vm_endpoints.go
index 9ea485378..469dff6b6 100644
--- a/cli/cmd/vm_endpoints.go
+++ b/cli/cmd/vm_endpoints.go
@@ -68,6 +68,8 @@ The output will be in the format: %s
 
 You can identify the VM either by its unique ID or by its name.
 
+By default, the username in the endpoint is the GitHub username linked to your Vendor Portal account. If the VM was created with 'replicated vm create --ssh-public-key', the Linux user on the VM is derived from the key's comment (the portion before the first '@') instead — pass that username via --username so the endpoint matches the user the key was added to.
+
 Note: %s endpoints can only be retrieved from VMs in the "running" state.
 
 VMs are currently a beta feature.`, protocol, outputFormat, protocol)
@@ -94,7 +96,7 @@ replicated vm %s-endpoint my-test-vm --username custom-user
 		Annotations:       map[string]string{"endpointType": endpointType},
 	}
 
-	cmd.Flags().String("username", "", fmt.Sprintf("Custom username to use in %s endpoint instead of the GitHub username set in Vendor Portal", protocol))
+	cmd.Flags().String("username", "", fmt.Sprintf("Custom username to use in %s endpoint instead of the GitHub username set in Vendor Portal. If the VM was created with 'replicated vm create --ssh-public-key', set this to the username derived from the key's comment (the portion before the first '@') so the endpoint matches the user the key was added to.", protocol))
 
 	parent.AddCommand(cmd)