agenticmail 0.5.0 → 0.5.2

package/README.md

@@ -76,6 +76,66 @@ Agent emails use proper addresses like `secretary@yourdomain.com`.
 
 ---
 
+## CLI Commands
+
+All commands are available via `agenticmail <command>` or `npx agenticmail@latest <command>`.
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `agenticmail` | **Start the server.** Runs setup first if not initialized, then starts all services and opens the interactive shell. This is the default — just run `agenticmail` with no arguments. |
+| `agenticmail setup` | **Run the setup wizard.** Walks you through system checks, account creation, service startup, email connection, phone number setup, and OpenClaw integration. Safe to re-run anytime. |
+| `agenticmail start` | **Start the server and open the interactive shell.** Ensures Docker is running, Stalwart is up, and the API server is reachable. Automatically installs the auto-start service. |
+| `agenticmail stop` | **Stop the server.** Kills the background API server process. If auto-start is enabled, it will restart on next boot. |
+| `agenticmail status` | **Show what's running.** Displays Docker, Stalwart, API server, email connection, and auto-start service status. |
+
+### Integration Commands
+
+| Command | Description |
+|---------|-------------|
+| `agenticmail openclaw` | **Set up AgenticMail for OpenClaw.** Starts infrastructure, creates an agent, configures the plugin, enables agent auto-spawn via hooks, and restarts the OpenClaw gateway. |
+
+### Service Management (Auto-Start on Boot)
+
+AgenticMail installs a system service so your email server starts automatically when your computer boots — no manual intervention needed.
+
+| Command | Description |
+|---------|-------------|
+| `agenticmail service` | **Show auto-start status.** Whether the service is installed and running. |
+| `agenticmail service install` | **Install the auto-start service.** On boot, the startup script waits up to 10 minutes for Docker, checks Stalwart (starts it if needed), then launches the API server. |
+| `agenticmail service uninstall` | **Remove the auto-start service.** AgenticMail will no longer start on boot. |
+| `agenticmail service reinstall` | **Reinstall the service.** Use after config changes or updates to refresh the service file. |
+
+**How auto-start works on reboot:**
+1. Computer starts → Docker Desktop launches (its own auto-start)
+2. Stalwart mail server starts (`restart: unless-stopped` in Docker)
+3. AgenticMail startup script waits for Docker to be ready (up to 10 min)
+4. Script verifies Stalwart is running (auto-starts it if needed)
+5. API server starts and begins accepting requests
+6. If the server crashes, the system service automatically restarts it
+
+On macOS this uses a LaunchAgent (`~/Library/LaunchAgents/com.agenticmail.server.plist`). On Linux it uses a systemd user service (`~/.config/systemd/user/agenticmail.service`).
+
+### Maintenance Commands
+
+| Command | Description |
+|---------|-------------|
+| `agenticmail update` | **Update to the latest version.** Checks npm, updates the CLI and OpenClaw plugin, and restarts the gateway. |
+| `agenticmail help` | **Show available commands.** |
+
+### Logs
+
+Server logs are stored in `~/.agenticmail/logs/`:
+
+| File | Contents |
+|------|----------|
+| `server.log` | API server stdout |
+| `server.err.log` | API server stderr |
+| `startup.log` | Boot sequence log — Docker wait times, Stalwart checks, startup events |
+
+---
+
 ## Starting the Server
 
 `agenticmail start` does three things:
@@ -98,6 +158,7 @@ If the server crashes, you get clear error output showing what went wrong.
 - **Account setup** — whether the config file and database exist
 - **Server health** — API server connectivity and Stalwart reachability
 - **Email gateway** — current mode (relay or domain), provider name, domain name, polling status
+- **Auto-start** — whether the system service is installed and running
 
 ---
 

package/dist/cli.js

@@ -9,7 +9,8 @@ import { createRequire } from "module";
 import { homedir } from "os";
 import JSON5 from "json5";
 import {
-  SetupManager
+  SetupManager,
+  ServiceManager
 } from "@agenticmail/core";
 
 // src/shell.ts
@@ -4428,6 +4429,10 @@ async function startApiServer(config) {
   const { spawn } = await import("child_process");
   const apiEntry = resolveApiEntry();
   const env = configToEnv(config);
+  try {
+    new ServiceManager().cacheApiEntryPath(apiEntry);
+  } catch {
+  }
   const child = spawn(process.execPath, [apiEntry], {
     detached: true,
     stdio: "ignore",
@@ -4879,6 +4884,23 @@ async function cmdSetup() {
     log2("");
     await registerWithOpenClaw(result.config);
   }
+  if (serverReady) {
+    const svcSpinner = new Spinner("general", "Setting up auto-start...");
+    svcSpinner.start();
+    try {
+      const svc = new ServiceManager();
+      const svcResult = svc.install();
+      if (svcResult.installed) {
+        svcSpinner.succeed(`${c2.bold("Auto-start")} \u2014 AgenticMail will start on boot`);
+      } else {
+        svcSpinner.fail(`Auto-start: ${svcResult.message}`);
+        info2("You can set this up later with: agenticmail service install");
+      }
+    } catch (err) {
+      svcSpinner.fail(`Auto-start: ${err.message}`);
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
   printSummary(result, false);
   if (serverReady) {
     await interactiveShell({ config: result.config, onExit: () => {
@@ -6223,6 +6245,23 @@ async function cmdStatus() {
     info2("Can't check email status \u2014 server isn't running");
   }
   log2("");
+  log2(`  ${c2.bold("Auto-Start:")}`);
+  try {
+    const svc = new ServiceManager();
+    const svcStatus = svc.status();
+    if (svcStatus.installed) {
+      if (svcStatus.running) {
+        ok2(`Enabled ${c2.dim(`(${svcStatus.platform}) \u2014 starts on boot`)}`);
+      } else {
+        ok2(`Installed ${c2.dim(`(${svcStatus.platform})`)} \u2014 ${c2.yellow("not currently running")}`);
+      }
+    } else {
+      fail2(`Not installed ${c2.dim("\u2014 run: agenticmail service install")}`);
+    }
+  } catch {
+    info2("Could not check auto-start status");
+  }
+  log2("");
 }
 async function cmdStart() {
   const setup = new SetupManager();
@@ -6273,19 +6312,107 @@ async function cmdStart() {
     serverSpinner.fail(`Couldn't start the server: ${err.message}`);
     process.exit(1);
   }
+  try {
+    const svc = new ServiceManager();
+    const svcStatus = svc.status();
+    if (!svcStatus.installed) {
+      const svcResult = svc.install();
+      if (svcResult.installed) {
+        ok2(`${c2.bold("Auto-start")} enabled \u2014 survives reboots`);
+      }
+    }
+  } catch {
+  }
   await interactiveShell({ config, onExit: () => {
   } });
 }
 async function cmdStop() {
   log2("");
   const stopped = stopApiServer();
-  if (stopped) {
+  const svc = new ServiceManager();
+  const svcStatus = svc.status();
+  if (svcStatus.installed && svcStatus.running) {
+    try {
+      if (svcStatus.platform === "launchd") {
+        const { execFileSync } = await import("child_process");
+        execFileSync("launchctl", ["unload", svcStatus.servicePath], { timeout: 1e4, stdio: "ignore" });
+      } else if (svcStatus.platform === "systemd") {
+        const { execFileSync } = await import("child_process");
+        execFileSync("systemctl", ["--user", "stop", "agenticmail.service"], { timeout: 1e4, stdio: "ignore" });
+      }
+    } catch {
+    }
+  }
+  if (stopped || svcStatus.installed && svcStatus.running) {
     ok2("AgenticMail server stopped");
+    if (svcStatus.installed) {
+      info2("Auto-start is still enabled. It will restart on next boot.");
+      info2(`To disable: ${c2.green("agenticmail service uninstall")}`);
+    }
   } else {
     info2("Server is not running");
   }
   log2("");
 }
+async function cmdService() {
+  const subCmd = process.argv[3] || "status";
+  const svc = new ServiceManager();
+  log2("");
+  switch (subCmd) {
+    case "install": {
+      const result = svc.install();
+      if (result.installed) {
+        ok2(`Auto-start service installed`);
+        info2(result.message);
+        info2("AgenticMail will now start automatically when your computer boots.");
+      } else {
+        fail2(result.message);
+      }
+      break;
+    }
+    case "uninstall":
+    case "remove": {
+      const result = svc.uninstall();
+      if (result.removed) {
+        ok2("Auto-start service removed");
+        info2("AgenticMail will no longer start on boot.");
+      } else {
+        fail2(result.message);
+      }
+      break;
+    }
+    case "reinstall": {
+      const result = svc.reinstall();
+      if (result.installed) {
+        ok2("Auto-start service reinstalled");
+        info2(result.message);
+      } else {
+        fail2(result.message);
+      }
+      break;
+    }
+    case "status":
+    default: {
+      const status = svc.status();
+      log2(`  ${c2.bold("Auto-Start Service")}`);
+      log2("");
+      if (status.installed) {
+        ok2(`Installed ${c2.dim(`(${status.platform})`)}`);
+        if (status.running) {
+          ok2(`Running`);
+        } else {
+          fail2(`Not running ${c2.dim("\u2014 will start on next boot or: agenticmail service reinstall")}`);
+        }
+        info2(`Service file: ${status.servicePath}`);
+      } else {
+        fail2("Not installed");
+        info2(`Install with: ${c2.green("agenticmail service install")}`);
+      }
+      break;
+    }
+  }
+  log2("");
+}
 async function cmdUpdate() {
   const { execSync } = await import("child_process");
   log2("");
@@ -6410,6 +6537,14 @@ switch (command) {
       process.exit(1);
     });
     break;
+  case "service":
+    cmdService().then(() => {
+      process.exit(0);
+    }).catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+    break;
   case "update":
     cmdUpdate().catch((err) => {
       console.error(err);
@@ -6429,6 +6564,7 @@ switch (command) {
     log2(`    ${c2.green("agenticmail stop")}      Stop the server`);
     log2(`    ${c2.green("agenticmail status")}    See what's running`);
     log2(`    ${c2.green("agenticmail openclaw")}  Set up AgenticMail for OpenClaw`);
+    log2(`    ${c2.green("agenticmail service")}   Manage auto-start (install/uninstall/status)`);
     log2(`    ${c2.green("agenticmail update")}    Update to the latest version`);
     log2("");
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticmail",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Email infrastructure for AI agents — send and receive real email programmatically",
   "type": "module",
   "main": "dist/index.js",