feat: add webmux service restart command

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hugocasa

README.md

@@ -52,19 +52,16 @@ Each issue is processed once while it stays in Todo + labeled. Remove the label
 
 When the auto-create watcher picks up a `webmux_oneshot` issue, it posts a structured comment on the Linear issue (prefix `` **Webmux pickup — branch `<branch>`** ``) so external automation can track when the autonomous run starts. (Regular `webmux` pickups are user-driven and skip the comment.)
 
-**Setup — `LINEAR_API_KEY`.** Everything above needs a [Linear API key](https://linear.app/settings/account/security) in the server's environment. Because webmux runs as a single machine-wide service (started from your home directory, not any one repo), provide the key in one of these ways — the first one found wins:
-
-1. **`~/.config/webmux/.env`** *(recommended)* — a simple `KEY=value` file the server loads at startup no matter which directory it runs from, so the key survives `webmux update` without touching the service unit:
-   ```bash
-   mkdir -p ~/.config/webmux
-   echo 'LINEAR_API_KEY=lin_api_...' >> ~/.config/webmux/.env
-   chmod 600 ~/.config/webmux/.env
-   systemctl --user restart webmux    # macOS: launchctl kickstart -k gui/$UID/com.webmux.webmux
-   ```
-2. **Baked into the service unit** — `webmux service install` auto-picks up `LINEAR_API_KEY` from your shell, or pass it explicitly with `webmux service install --env LINEAR_API_KEY=lin_api_...`. Re-run after rotating the key.
-3. **A project `.env` / `.env.local`** in the directory you launch `webmux serve` from — loaded at startup, and overrides the global file above for that session. Handy for a foreground `webmux serve`, but not read by the background service (which runs from `$HOME`).
-
-If issues don't appear, confirm the running service actually sees the key — `systemctl --user show webmux -p Environment` (baked-in case) — or that `~/.config/webmux/.env` exists and the service was restarted after you wrote it.
+**Setup — `LINEAR_API_KEY`.** Everything above needs a [Linear API key](https://linear.app/settings/account/security) in the server's environment. webmux runs as a single machine-wide service started from your home directory, so put the key in `~/.config/webmux/.env` — a `KEY=value` file the server loads at startup regardless of which directory it runs from, so it survives `webmux update`:
+
+```bash
+mkdir -p ~/.config/webmux
+echo 'LINEAR_API_KEY=lin_api_...' >> ~/.config/webmux/.env
+chmod 600 ~/.config/webmux/.env
+webmux service restart
+```
+
+Your assigned issues appear in the dashboard once the service restarts.
 
 ## Quick Start
 

bin/src/service.test.ts

@@ -6,6 +6,7 @@ import {
   parseInstalledServiceConfig,
   readEnvVarsFromUnit,
   readPortFromUnit,
+  restartCommands,
   resolveConfirmDecision,
   resolveEnvVars,
   shouldPersistProject,
@@ -59,6 +60,29 @@ describe("resolveConfirmDecision", () => {
   });
 });
 
+describe("restartCommands", () => {
+  const base: ServiceConfig = {
+    platform: "linux",
+    serviceName: "webmux",
+    webmuxPath: "/usr/bin/webmux",
+    port: 5111,
+    envVars: {},
+  };
+
+  it("restarts the user unit on linux", () => {
+    expect(restartCommands(base)).toEqual([
+      ["systemctl", ["--user", "restart", "webmux"]],
+    ]);
+  });
+
+  it("kickstarts the labeled agent on darwin", () => {
+    const [[bin, args]] = restartCommands({ ...base, platform: "darwin" });
+    expect(bin).toBe("launchctl");
+    expect(args.slice(0, 2)).toEqual(["kickstart", "-k"]);
+    expect(args[2]).toMatch(/^gui\/\d+\/com\.webmux\.webmux$/);
+  });
+});
+
 describe("shouldPersistProject", () => {
   it("persists a webmux repo that isn't registered yet", () => {
     expect(shouldPersistProject("/some/repo", true, ["/other/repo"])).toBe(true);

bin/src/service.ts

@@ -339,6 +339,14 @@ function uninstallCommands(config: ServiceConfig): Command[] {
   ];
 }
 
+export function restartCommands(config: ServiceConfig): Command[] {
+  if (config.platform === "linux") {
+    return [["systemctl", ["--user", "restart", config.serviceName]]];
+  }
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+  return [["launchctl", ["kickstart", "-k", `gui/${uid}/com.webmux.${config.serviceName}`]]];
+}
+
 // ── Check if service exists ─────────────────────────────────────────────────
 
 function isInstalled(config: ServiceConfig): boolean {
@@ -650,6 +658,22 @@ async function uninstall(config: ServiceConfig): Promise<void> {
   p.log.success("Service uninstalled.");
 }
 
+function restart(config: ServiceConfig): void {
+  if (!isInstalled(config)) {
+    p.log.error("Service is not installed.");
+    return;
+  }
+
+  for (const cmd of restartCommands(config)) {
+    const result = runCommand(cmd);
+    if (!result.success) {
+      p.log.error(`Command failed: ${formatCommand(cmd)}\n${result.stderr.toString()}`);
+      return;
+    }
+  }
+  p.log.success("Service restarted.");
+}
+
 function status(config: ServiceConfig): void {
   if (!isInstalled(config)) {
     p.log.error("Service is not installed.");
@@ -702,6 +726,7 @@ add more projects from the dashboard or with \`webmux project add\`.
 Usage:
   webmux service install     Install, enable, and start the service
   webmux service uninstall   Stop, disable, and remove the service
+  webmux service restart     Restart the service (e.g. to reload config env)
   webmux service status      Show service status
   webmux service logs        Tail service logs
 
@@ -736,7 +761,7 @@ export default async function service(args: string[]): Promise<void> {
     return;
   }
 
-  if (!["install", "uninstall", "status", "logs"].includes(action)) {
+  if (!["install", "uninstall", "restart", "status", "logs"].includes(action)) {
     p.log.error(`Unknown action: ${action}`);
     usage();
     return;
@@ -828,6 +853,9 @@ export default async function service(args: string[]): Promise<void> {
     case "uninstall":
       await uninstall(config);
       break;
+    case "restart":
+      restart(config);
+      break;
     case "status":
       status(config);
       break;