Add cmux vm command aliases

CLI/cmux.swift

@@ -3992,11 +3992,11 @@ struct CMUXCLI {
                 )
                 Self.clearVMCreateIdempotency(idempotency)
 
-            case "shell", "attach":
+            case "shell", "attach", "connect":
                 let (windowOpt, vmArgs) = parseOption(rest, name: "--window")
                 guard let vmId = vmArgs.first else {
                     throw CLIError(message: """
-                        Usage: cmux \(command) shell <id>
+                        Usage: cmux vm ssh <id>
 
                         Find an id:
                           cmux vm ls
@@ -4012,7 +4012,7 @@ struct CMUXCLI {
                     idFormat: idFormat
                 )
 
-            case "rm", "destroy", "delete":
+            case "rm", "remove", "destroy", "delete":
                 guard let vmId = rest.first else {
                     throw CLIError(message: """
                         Usage: cmux vm rm <id>
@@ -4118,13 +4118,19 @@ struct CMUXCLI {
 
             default:
                 throw CLIError(message: """
-                    Usage: cmux \(command) <ls|new|shell|rm|exec|ssh> [args...]
+                    Usage: cmux \(command) <new|ls|rm|exec|ssh|ssh-info> [args...]
 
                     Common commands:
                       cmux vm ls
                       cmux vm new
                       cmux vm ssh <id>
                       cmux vm rm <id>
+
+                    Aliases are available for familiar spelling:
+                      create -> new
+                      list -> ls
+                      shell, attach, connect -> ssh
+                      remove, delete, destroy -> rm
                     """)
             }
 
@@ -14436,7 +14442,7 @@ struct CMUXCLI {
             """
         case "vm", "cloud":
             return """
-            Usage: cmux \(command) <new|ls|rm|exec|shell|attach|ssh|ssh-info> [args...]
+            Usage: cmux \(command) <new|ls|rm|exec|ssh|ssh-info> [args...]
 
             Manage cloud VMs. `cloud` is an alias for `vm`. Requires `cmux auth login`.
 
@@ -14446,9 +14452,6 @@ struct CMUXCLI {
                                         Create a new VM. By default drops you into a shell on
                                         the VM (like `docker run -it`). Pass --detach/-d to
                                         just print the id and exit (scripting primitive).
-              shell <id> [--window <id|ref|index>]
-                                        Drop into an interactive shell on an existing VM.
-                                        Alias: `attach <id>`.
               ssh <id> [--window <id|ref|index>]
                                         Drop into a cmux-managed SSH workspace for an existing
                                         VM, using the same session path as `cmux ssh`.
@@ -14457,6 +14460,12 @@ struct CMUXCLI {
               rm <id>                   Destroy a VM.
               exec <id> -- <command...> Run a shell command inside the VM and print stdout.
 
+            Aliases:
+              create                     Alias for `new`; prefer `new` in docs and scripts.
+              list                       Alias for `ls`; prefer `ls` in docs and scripts.
+              shell, attach, connect     Aliases for `ssh`; prefer `ssh` in docs and scripts.
+              remove, delete, destroy    Aliases for `rm`; prefer `rm` in docs and scripts.
+
             Env:
               CMUX_VM_API_BASE_URL       Override the backend origin (default: the cmux website).
                                          `bun run dev` derives this from CMUX_PORT/PORT for
@@ -34262,7 +34271,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
           events [--after <seq>] [--cursor-file <path>] [--name <event>] [--category <category>] [--reconnect] [--limit <n>] [--no-ack] [--no-heartbeat]
           auth <status|login|logout>
           login | logout                                      (aliases for auth login/logout)
-          vm <new|ls|rm|exec|shell|ssh> [args...]    (alias: cloud)
+          vm <new|ls|rm|exec|ssh|ssh-info> [args...]    (alias: cloud; accepts create/list/attach/remove aliases)
           remotes <list|add|remove> [--route <host:port>] [--tag <tag>] [--json]    (alias: remote)
           rpc <method> [json-params]
           identify [--workspace <id|ref|index>] [--surface <id|ref|index>] [--window <id|ref|index>] [--no-caller]

cmuxTests/VMSSHCommandTests.swift

@@ -2,6 +2,211 @@ import XCTest
 import Darwin
 
 extension CLINotifyProcessIntegrationRegressionTests {
+    func testVMCreateAliasDispatchesThroughVMCreate() throws {
+        let cliPath = try bundledCLIPath()
+        let socketPath = makeSocketPath("vm-create-alias")
+        let listenerFD = try bindUnixSocket(at: socketPath)
+        let state = MockSocketServerState()
+        let tempHome = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+            .appendingPathComponent("cmux-vm-create-alias-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: tempHome, withIntermediateDirectories: true)
+
+        defer {
+            Darwin.close(listenerFD)
+            unlink(socketPath)
+            try? FileManager.default.removeItem(at: tempHome)
+        }
+
+        let serverHandled = startMockServer(listenerFD: listenerFD, state: state) { line in
+            guard let payload = self.jsonObject(line),
+                  let id = payload["id"] as? String,
+                  let method = payload["method"] as? String else {
+                return self.malformedRequestResponse(raw: line)
+            }
+            guard method == "vm.create" else {
+                return self.v2Response(id: id, ok: false, error: ["code": "unexpected", "message": "Unexpected method \(method)"])
+            }
+            let params = payload["params"] as? [String: Any] ?? [:]
+            XCTAssertEqual(params["provider"] as? String, "freestyle")
+            XCTAssertNotNil(params["idempotency_key"] as? String)
+            return self.v2Response(
+                id: id,
+                ok: true,
+                result: [
+                    "id": "vm-create-alias",
+                    "provider": "freestyle",
+                    "image": "default",
+                ]
+            )
+        }
+
+        var environment = ProcessInfo.processInfo.environment
+        environment["CMUX_SOCKET_PATH"] = socketPath
+        environment["CMUX_CLI_SENTRY_DISABLED"] = "1"
+        environment["CMUX_CLAUDE_HOOK_SENTRY_DISABLED"] = "1"
+        environment["CFFIXED_USER_HOME"] = tempHome.path
+
+        let result = runProcess(
+            executablePath: cliPath,
+            arguments: ["vm", "create", "--provider", "freestyle", "--detach"],
+            environment: environment,
+            timeout: 5
+        )
+
+        wait(for: [serverHandled], timeout: 5)
+        XCTAssertFalse(result.timedOut, result.stderr)
+        XCTAssertEqual(result.status, 0, result.stderr)
+        XCTAssertTrue(result.stdout.contains("OK vm-create-alias"), result.stdout)
+        XCTAssertEqual(
+            state.commands.compactMap { self.jsonObject($0)?["method"] as? String },
+            ["vm.create"]
+        )
+    }
+
+    func testVMRemoveAliasDispatchesThroughVMDestroy() throws {
+        let cliPath = try bundledCLIPath()
+        let socketPath = makeSocketPath("vm-remove-alias")
+        let listenerFD = try bindUnixSocket(at: socketPath)
+        let state = MockSocketServerState()
+        let vmID = "vm-remove-alias"
+
+        defer {
+            Darwin.close(listenerFD)
+            unlink(socketPath)
+        }
+
+        let serverHandled = startMockServer(listenerFD: listenerFD, state: state) { line in
+            guard let payload = self.jsonObject(line),
+                  let id = payload["id"] as? String,
+                  let method = payload["method"] as? String else {
+                return self.malformedRequestResponse(raw: line)
+            }
+            guard method == "vm.destroy" else {
+                return self.v2Response(id: id, ok: false, error: ["code": "unexpected", "message": "Unexpected method \(method)"])
+            }
+            let params = payload["params"] as? [String: Any] ?? [:]
+            XCTAssertEqual(params["id"] as? String, vmID)
+            return self.v2Response(id: id, ok: true, result: ["ok": true])
+        }
+
+        var environment = ProcessInfo.processInfo.environment
+        environment["CMUX_SOCKET_PATH"] = socketPath
+        environment["CMUX_CLI_SENTRY_DISABLED"] = "1"
+        environment["CMUX_CLAUDE_HOOK_SENTRY_DISABLED"] = "1"
+
+        let result = runProcess(
+            executablePath: cliPath,
+            arguments: ["vm", "remove", vmID],
+            environment: environment,
+            timeout: 5
+        )
+
+        wait(for: [serverHandled], timeout: 5)
+        XCTAssertFalse(result.timedOut, result.stderr)
+        XCTAssertEqual(result.status, 0, result.stderr)
+        XCTAssertEqual(result.stdout, "OK \(vmID)\n")
+        XCTAssertEqual(
+            state.commands.compactMap { self.jsonObject($0)?["method"] as? String },
+            ["vm.destroy"]
+        )
+    }
+
+    func testVMConnectAliasOpensManagedWorkspaceThroughSharedSSHPath() throws {
+        let cliPath = try bundledCLIPath()
+        let socketPath = makeSocketPath("vm-connect")
+        let listenerFD = try bindUnixSocket(at: socketPath)
+        let state = MockSocketServerState()
+        let vmID = "vm-connect-1234567890"
+        let workspaceID = "11111111-1111-1111-1111-111111111111"
+        let workspaceRef = "workspace:connect"
+
+        defer {
+            Darwin.close(listenerFD)
+            unlink(socketPath)
+        }
+
+        let serverHandled = startMockServer(listenerFD: listenerFD, state: state) { line in
+            guard let payload = self.jsonObject(line),
+                  let id = payload["id"] as? String,
+                  let method = payload["method"] as? String else {
+                return self.malformedRequestResponse(raw: line)
+            }
+
+            switch method {
+            case "vm.attach_info":
+                let params = payload["params"] as? [String: Any] ?? [:]
+                XCTAssertEqual(params["id"] as? String, vmID)
+                XCTAssertEqual(params["require_daemon"] as? Bool, true)
+                return self.v2Response(
+                    id: id,
+                    ok: true,
+                    result: [
+                        "transport": "ssh",
+                        "host": "gateway.freestyle.sh",
+                        "port": 2222,
+                        "username": "cmux",
+                        "credential": [
+                            "kind": "password",
+                            "value": "lease-token",
+                        ],
+                    ]
+                )
+            case "workspace.create":
+                return self.v2Response(
+                    id: id,
+                    ok: true,
+                    result: [
+                        "workspace_id": workspaceID,
+                    ]
+                )
+            case "workspace.rename":
+                return self.v2Response(id: id, ok: true, result: ["workspace_id": workspaceID])
+            case "workspace.remote.configure":
+                return self.v2Response(
+                    id: id,
+                    ok: true,
+                    result: [
+                        "workspace_id": workspaceID,
+                        "workspace_ref": workspaceRef,
+                        "remote": [
+                            "enabled": true,
+                            "state": "connecting",
+                        ],
+                    ]
+                )
+            case "workspace.select":
+                return self.v2Response(id: id, ok: true, result: ["workspace_id": workspaceID])
+            default:
+                return self.v2Response(
+                    id: id,
+                    ok: false,
+                    error: ["code": "unexpected", "message": "Unexpected method \(method)"]
+                )
+            }
+        }
+
+        var environment = ProcessInfo.processInfo.environment
+        environment["CMUX_SOCKET_PATH"] = socketPath
+        environment["CMUX_CLI_SENTRY_DISABLED"] = "1"
+        environment["CMUX_CLAUDE_HOOK_SENTRY_DISABLED"] = "1"
+
+        let result = runProcess(
+            executablePath: cliPath,
+            arguments: ["vm", "connect", vmID],
+            environment: environment,
+            timeout: 5
+        )
+
+        wait(for: [serverHandled], timeout: 5)
+        XCTAssertFalse(result.timedOut, result.stderr)
+        XCTAssertEqual(result.status, 0, result.stderr)
+        XCTAssertEqual(result.stdout, "OK workspace=\(workspaceRef) target=cmux@gateway.freestyle.sh state=connecting\n")
+        XCTAssertEqual(
+            state.commands.compactMap { self.jsonObject($0)?["method"] as? String },
+            ["vm.attach_info", "workspace.create", "workspace.rename", "workspace.remote.configure", "workspace.select"]
+        )
+    }
+
     func testVMSSHOpensManagedWorkspaceThroughSharedSSHPath() throws {
         let cliPath = try bundledCLIPath()
         let socketPath = makeSocketPath("vm-ssh")

docs/cli-contract.md

@@ -190,11 +190,10 @@ VM subcommands:
 
 | Command | Contract |
 | --- | --- |
-| `vm ls`, `vm list` | List VMs. |
-| `vm new`, `vm create` | Create a VM. Supports `--image`, `--provider`, `--detach`, and `-d`. |
-| `vm shell`, `vm attach` | Open an interactive shell for an existing VM. |
-| `vm rm`, `vm destroy`, `vm delete` | Destroy a VM. |
-| `vm ssh` | Open a cmux-managed SSH workspace for an existing VM. |
+| `vm ls` | List VMs. Alias: `list`. Prefer `ls` in docs and scripts. |
+| `vm new` | Create a VM. Supports `--image`, `--provider`, `--detach`, and `-d`. Alias: `create`. Prefer `new` in docs and scripts. |
+| `vm ssh` | Open a cmux-managed SSH workspace for an existing VM. Aliases: `shell`, `attach`, `connect`. Prefer `ssh` in docs and scripts. |
+| `vm rm` | Destroy a VM. Aliases: `remove`, `destroy`, `delete`. Prefer `rm` in docs and scripts. |
 | `vm ssh-info` | Print SSH connection info. |
 | `vm ssh-attach` | Internal attach helper. |
 | `vm exec` | Run a shell command inside a VM. |
@@ -444,8 +443,8 @@ the expected text without connecting to a cmux socket.
 - `cmux capabilities --help` -> `Usage: cmux capabilities`
 - `cmux events --help` -> `Usage: cmux events [options]`
 - `cmux auth --help` -> `Usage: cmux auth <status|login|logout>`
-- `cmux vm --help` -> `Usage: cmux vm <new|ls|rm|exec|shell|attach|ssh|ssh-info> [args...]`
-- `cmux cloud --help` -> `Usage: cmux cloud <new|ls|rm|exec|shell|attach|ssh|ssh-info> [args...]`
+- `cmux vm --help` -> `Usage: cmux vm <new|ls|rm|exec|ssh|ssh-info> [args...]`
+- `cmux cloud --help` -> `Usage: cmux cloud <new|ls|rm|exec|ssh|ssh-info> [args...]`
 - `cmux remotes --help` -> `Usage: cmux remotes <list|add|remove> [options]`
 - `cmux remote --help` -> `Usage: cmux remotes <list|add|remove> [options]`
 - `cmux rpc --help` -> `Usage: cmux rpc <method> [json-params]`