refactor: use Commander.js for top-level CLI routing

- Replace manual argv parsing with proper Commander.js subcommands
- Add --version flag with proper version info
- Subcommands (run, server) now properly routed via executableFile
- Default action launches desktop app when no subcommand given
- Update docs to reflect --version flag instead of subcommand

Author: ammar-agent

docs/cli.md

@@ -1,10 +1,10 @@
 # Command Line Interface
 
-Mux provides a CLI for running agent sessions without opening the desktop app.
+Mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, `mux run` executes a single request to completion and exits.
 
 ## `mux run`
 
-Run an agent session in any directory:
+Execute a one-off agent task:
 
 ```bash
 # Basic usage - run in current directory
@@ -16,9 +16,6 @@ mux run --dir /path/to/project "Add authentication"
 # Use SSH runtime
 mux run --runtime "ssh user@myserver" "Deploy changes"
 
-# Plan mode (proposes a plan, then auto-executes)
-mux run --mode plan "Refactor the auth module"
-
 # Pipe instructions via stdin
 echo "Add logging to all API endpoints" | mux run
 
@@ -67,9 +64,6 @@ mux run -r "ssh dev@staging.example.com" -d /app "Update dependencies"
 
 # Scripted usage with timeout
 mux run --json --timeout 5m "Generate API documentation" > output.jsonl
-
-# Plan first, then execute
-mux run --mode plan "Migrate from REST to GraphQL"
 ```
 
 ## `mux server`
@@ -87,11 +81,11 @@ Options:
 - `--auth-token <token>` - Optional bearer token for authentication
 - `--add-project <path>` - Add and open project at the specified path
 
-## `mux version`
+## `mux --version`
 
 Print the version and git commit:
 
 ```bash
-mux version
-# mux v0.8.4 (abc123)
+mux --version
+# v0.8.4 (abc123)
 ```

src/cli/index.ts

@@ -1,24 +1,22 @@
 #!/usr/bin/env node
+import { Command } from "commander";
+import { VERSION } from "../version";
 
-const subcommand = process.argv.length > 2 ? process.argv[2] : null;
+const program = new Command();
 
-if (subcommand === "server") {
-  // Remove 'server' from args since main-server doesn't expect it as a positional argument.
-  process.argv.splice(2, 1);
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  require("./server");
-} else if (subcommand === "run") {
-  // Remove 'run' from args since run.ts uses Commander which handles its own parsing
-  process.argv.splice(2, 1);
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  require("./run");
-} else if (subcommand === "version") {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { VERSION } = require("../version") as {
-    VERSION: { git_describe: string; git_commit: string };
-  };
-  console.log(`mux ${VERSION.git_describe} (${VERSION.git_commit})`);
-} else {
+program
+  .name("mux")
+  .description("Mux - AI agent orchestration")
+  .version(`${VERSION.git_describe} (${VERSION.git_commit})`, "-v, --version");
+
+program
+  .command("run", "Run a one-off agent session", { executableFile: "./run" })
+  .command("server", "Start the HTTP/WebSocket ORPC server", { executableFile: "./server" });
+
+// Default to desktop app when no subcommand given
+program.action(() => {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   require("../desktop/main");
-}
+});
+
+program.parse();

src/cli/server.ts

@@ -13,7 +13,7 @@ import type { ORPCContext } from "@/node/orpc/context";
 
 const program = new Command();
 program
-  .name("mux-server")
+  .name("mux server")
   .description("HTTP/WebSocket ORPC server for mux")
   .option("-h, --host <host>", "bind to specific host", "localhost")
   .option("-p, --port <port>", "bind to specific port", "3000")

src/node/services/mock/scenarios/slashCommands.ts

@@ -65,26 +65,26 @@ const modelStatusTurn: ScenarioTurn = {
         kind: "stream-start",
         delay: 0,
         messageId: "msg-slash-model-status",
-        model: "anthropic:claude-opus-4-5",
+        model: "anthropic:claude-sonnet-4-5",
       },
       {
         kind: "stream-delta",
         delay: STREAM_BASE_DELAY,
-        text: "Claude Opus 4.5 is now responding with enhanced reasoning capacity.",
+        text: "Claude Sonnet 4.5 is now responding with standard reasoning capacity.",
       },
       {
         kind: "stream-end",
         delay: STREAM_BASE_DELAY * 2,
         metadata: {
-          model: "anthropic:claude-opus-4-5",
+          model: "anthropic:claude-sonnet-4-5",
           inputTokens: 70,
           outputTokens: 54,
           systemMessageTokens: 12,
         },
         parts: [
           {
             type: "text",
-            text: "I'm responding as Claude Opus 4.5, which you selected via /model opus. Let me know how to proceed.",
+            text: "I'm responding as Claude Sonnet 4.5, which you selected via /model sonnet. Let me know how to proceed.",
           },
         ],
       },

tests/e2e/scenarios/slashCommands.spec.ts

@@ -99,26 +99,27 @@ test.describe("slash command flows", () => {
     await expect(transcript).not.toContainText("Directory listing:");
   });
 
-  test("slash command /model opus switches models for subsequent turns", async ({ ui, page }) => {
+  test("slash command /model sonnet switches models for subsequent turns", async ({ ui, page }) => {
     await ui.projects.openFirstWorkspace();
 
     const modeToggles = page.locator('[data-component="ChatModeToggles"]');
+    // Default model is now Opus
+    await expect(modeToggles.getByText("anthropic:claude-opus-4-5", { exact: true })).toBeVisible();
+
+    await ui.chat.sendMessage("/model sonnet");
+    await ui.chat.expectStatusMessageContains("Model changed to anthropic:claude-sonnet-4-5");
     await expect(
       modeToggles.getByText("anthropic:claude-sonnet-4-5", { exact: true })
     ).toBeVisible();
 
-    await ui.chat.sendMessage("/model opus");
-    await ui.chat.expectStatusMessageContains("Model changed to anthropic:claude-opus-4-5");
-    await expect(modeToggles.getByText("anthropic:claude-opus-4-5", { exact: true })).toBeVisible();
-
     const timeline = await ui.chat.captureStreamTimeline(async () => {
       await ui.chat.sendMessage(SLASH_COMMAND_PROMPTS.MODEL_STATUS);
     });
 
     const streamStart = timeline.events.find((event) => event.type === "stream-start");
-    expect(streamStart?.model).toBe("anthropic:claude-opus-4-5");
+    expect(streamStart?.model).toBe("anthropic:claude-sonnet-4-5");
     await ui.chat.expectTranscriptContains(
-      "Claude Opus 4.5 is now responding with enhanced reasoning capacity."
+      "Claude Sonnet 4.5 is now responding with standard reasoning capacity."
     );
   });