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

@@ -87,11 +87,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")