@clawops/cli 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # clawops
 
-Deploy OpenClaw once. Operate it from your terminal or Claude Code.
+MCP-native infrastructure ops for OpenClaw — with read-only mode, destructive-action confirmation, and audit logs built in.
 
 **clawops** is a CLI and [MCP](https://modelcontextprotocol.io/) server for deploying and operating
 self-hosted [OpenClaw](https://github.com/openclaw/openclaw) instances. Provision on AWS, GCP,
@@ -45,78 +45,140 @@ and Cursor drive them through typed MCP tools with explicit safety controls.
 
 ---
 
-## Quick Start — local VM (fastest path)
+## Quick Start
 
-The local provider needs only a Linux host reachable over SSH — no cloud account required.
+```bash
+npm install -g @clawops/cli
+clawops setup
+```
+
+`clawops setup` is an interactive wizard that gets OpenClaw running in about 2 minutes. It
+handles everything in one flow — no config files to write by hand, no commands to memorize.
+
+### What the wizard does
+
+**Step 1 — Choose a deployment target**
+
+Pick an existing server you can SSH into (Linux or macOS), or a new cloud VM on AWS, GCP, or
+Azure. Cloud deployments walk you through authenticating with the provider CLI if you aren't
+already signed in.
+
+**Step 2 — Pick an LLM provider**
+
+Choose from Anthropic, OpenAI, Amazon Bedrock, Ollama, or others. The wizard prompts for your
+API key and saves it locally (in `~/.clawops/secrets/`, chmod 600) — it is never sent anywhere
+except to OpenClaw on the target host when the config is applied.
+
+**Step 3 — Add chat integrations (optional)**
+
+Select any combination of Discord, Telegram, Slack, WhatsApp, or Teams. The wizard collects each
+integration's bot token the same way as the API key — paste it in, reference an env var, or point
+to a file.
+
+**Step 4 — Wire your AI editor**
+
+Select which AI apps should have access to clawops — Claude Desktop, Claude Code, Cursor,
+Windsurf, VS Code, and Zed are all supported. The wizard writes an MCP server entry into each
+app's config file using the absolute binary path so the app can launch it independently.
 
-**Prerequisites:** Node.js ≥ 22, an SSH key, a Linux host (Ubuntu/Debian/RHEL) you can reach.
+**Step 5 — Deploy**
+
+The wizard bootstraps OpenClaw on the target host over SSH (installs Docker, pulls the image,
+starts the container), applies your LLM and integration config, generates a gateway auth token,
+and prints a direct dashboard URL:
+
+```
+✔ All done! OpenClaw is running.
+ℹ Open dashboard: http://192.168.1.50:18789?token=<your-token>
+ℹ Token saved to ~/.clawops/secrets/GATEWAY_TOKEN_my-stack
+```
+
+**Prerequisites:** Node.js ≥ 22, an SSH key, and either an SSH-reachable Linux/macOS host or a
+cloud account with CLI credentials configured (`aws configure`, `gcloud auth login`, or `az login`).
+
+For a full narrated walkthrough with example output, see [`docs/demo-script.md`](docs/demo-script.md).
+
+---
+
+### Manual setup — existing server
+
+If you prefer step-by-step control, or are adding clawops to an already-running deployment:
 
 ```bash
 npm install -g @clawops/cli
 
-# Check your environment
-clawops doctor
+clawops doctor   # verify environment
 
-# Configure clawops for a local host
 clawops init --provider local --host 192.168.1.50 --user ubuntu --key-path ~/.ssh/id_ed25519
-
-# Bootstrap OpenClaw on the host (installs Docker + OpenClaw over SSH)
-clawops up
-
-# Verify it's running
+clawops up       # installs Docker + OpenClaw over SSH
 clawops status
-
-# Start the MCP server for Claude Code
-clawops mcp serve
 ```
 
-See [`docs/examples/local-vm.md`](docs/examples/local-vm.md) for the full walkthrough including
-SSH prerequisites, firewall setup, and troubleshooting.
+See [`docs/examples/local-vm.md`](docs/examples/local-vm.md) for SSH prerequisites, firewall
+setup, and troubleshooting.
 
-## Quick Start — cloud (AWS)
+### Manual setup — cloud (AWS)
 
 ```bash
 npm install -g @clawops/cli
-# or: npx @clawops/cli
 
 # Requires AWS credentials in your environment (AWS_PROFILE or ~/.aws/credentials)
 clawops init --provider aws
 
-# Edit ~/.clawops/config.json — set stateUrl to your S3 bucket:
-#   "stateUrl": "s3://my-clawops-state"
+# Edit ~/.clawops/config.json — set stateUrl to your S3 bucket
 
-# Generate a deploy plan (runs pulumi preview internally)
 clawops plan --provider aws --stack default --out /tmp/plan.json
-
-# Review the plan, then apply
 clawops apply /tmp/plan.json
 ```
 
 ---
 
-## Connect Claude Code
+## Connect an AI editor
+
+The `setup` wizard handles this automatically (Step 4). To wire or re-wire editors at any time:
+
+```bash
+clawops mcp install
+```
+
+This opens the same interactive checkbox used in the wizard — select Claude Desktop, Claude Code,
+Cursor, Windsurf, VS Code, or Zed and clawops writes the MCP entry into each app's config using
+the correct absolute binary path.
 
-Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
+To add the entry manually instead, paste this into your editor's MCP config:
 
 ```json
 {
   "mcpServers": {
     "clawops": {
-      "command": "clawops",
+      "command": "/path/to/clawops",
       "args": ["mcp", "serve", "--read-only"]
     }
   }
 }
 ```
 
+Replace `/path/to/clawops` with the output of `which clawops`. Config file locations:
+
+| App | Path |
+|---|---|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Claude Code | `~/.claude.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (macOS) | `~/Library/Application Support/Code/User/mcp.json` |
+| VS Code (Linux) | `~/.config/Code/User/mcp.json` |
+| Zed | `~/.config/zed/settings.json` (key: `context_servers`) |
+
 **Start with `--read-only`** — it enables status, logs, config reads, and diagnostics while
-blocking any operation that mutates infrastructure. Remove `--read-only` only once you understand
-which tools are destructive and have reviewed [`docs/security/mcp-safety.md`](docs/security/mcp-safety.md).
+blocking mutations. Remove it only after reviewing
+[`docs/security/mcp-safety.md`](docs/security/mcp-safety.md).
 
 Destructive tools (`clawops_destroy`, `clawops_up`, `clawops_config_set`, etc.) require explicit
-confirmation from the agent before executing — they will never run silently.
+confirmation before executing — they will never run silently.
 
-For Cursor, VS Code, or HTTP mode setup see [`docs/mcp/`](docs/mcp/).
+For HTTP mode setup see [`docs/mcp/`](docs/mcp/).
 
 ---
 
@@ -160,7 +222,9 @@ clawops down --yes          # Destroy local-provider stack
 | `backup` | Create or restore an OpenClaw state backup |
 | `stacks` | List named stacks and their state |
 | `doctor` | Check Node version, config, SSH key, provider credentials, and Pulumi home |
-| `mcp` | Start the embedded MCP server (`mcp serve`) |
+| `mcp serve` | Start the embedded MCP server (stdio or HTTP) |
+| `mcp install` | Interactively wire clawops into AI editors |
+| `help` | List all commands and global flags |
 
 Full flag reference: `clawops <command> --help`
 
@@ -198,23 +262,29 @@ See [`docs/plan-apply.md`](docs/plan-apply.md) for full semantics, drift guidanc
 clawops ships an embedded [MCP](https://modelcontextprotocol.io/) server. Claude Code, Cursor, and
 any MCP-compatible agent can drive deployments without leaving the chat interface.
 
-### Stdio mode (Claude Code / VS Code)
+### Wire your editor
 
-```json
-{
-  "mcpServers": {
-    "clawops": {
-      "command": "clawops",
-      "args": ["mcp", "serve", "--read-only"]
-    }
-  }
-}
+```bash
+clawops mcp install   # interactive checkbox — writes config for selected apps
+```
+
+The wizard resolves the absolute binary path automatically so app launchers can find `clawops`
+without inheriting your shell's `PATH`. See [Connect an AI editor](#connect-an-ai-editor) above
+for manual config paths.
+
+### Stdio mode (Claude Code / Cursor / VS Code)
+
+Start the server manually or confirm your config is correct:
+
+```bash
+clawops mcp serve --read-only   # safe for first evaluation
+clawops mcp serve               # full mode — enables provisioning, config write, ssh exec
 ```
 
 ### HTTP mode (remote / multi-client)
 
 ```bash
-clawops mcp serve --http --port 3333 --bind 127.0.0.1
+clawops mcp serve --http 3333 --bind 127.0.0.1
 # MCP HTTP server listening on 127.0.0.1:3333
 ```
 

package/dist/{apply-KBF7OPWL.js → apply-DLNE2JYZ.js}

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import {
   applyPlan
-} from "./chunk-LU63NZD3.js";
+} from "./chunk-JCUZU5BH.js";
 import "./chunk-YTH4L2GN.js";
+import "./chunk-6ZFIFDBJ.js";
 import "./chunk-BOPSG2LI.js";
-import "./chunk-ACYJBSLJ.js";
-import "./chunk-BRPU7AQC.js";
+import "./chunk-JDN6PLH2.js";
 import "./chunk-UDNZUSKA.js";
+import "./chunk-A2I76FTA.js";
 import "./chunk-CX5SL5HP.js";
 import "./chunk-KGXPLI7W.js";
 export {

package/dist/{bootstrap-UYCOEJQX.js → bootstrap-G4UZ2FKH.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import {
-  writeLocalState
-} from "./chunk-BRPU7AQC.js";
 import {
   acquireSession
 } from "./chunk-ZVOEQCNW.js";
 import "./chunk-4U3LTLWZ.js";
+import {
+  writeLocalState
+} from "./chunk-A2I76FTA.js";
 import "./chunk-CX5SL5HP.js";
 import {
   ProviderError

package/dist/chunk-6ZFIFDBJ.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+// src/plan/overlay-store.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import path from "path";
+import os from "os";
+function overlayPath(stackName) {
+  return path.join(os.homedir(), ".clawops", "overlays", `${stackName}.json`);
+}
+function saveOverlay(stackName, overlay, secrets) {
+  const dir = path.join(os.homedir(), ".clawops", "overlays");
+  mkdirSync(dir, { recursive: true });
+  const data = { stackName, savedAt: (/* @__PURE__ */ new Date()).toISOString(), overlay, secrets };
+  writeFileSync(overlayPath(stackName), JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function loadOverlay(stackName) {
+  const p = overlayPath(stackName);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function listOverlays() {
+  const dir = path.join(os.homedir(), ".clawops", "overlays");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json")).flatMap((f) => {
+    try {
+      return [JSON.parse(readFileSync(path.join(dir, f), "utf-8"))];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export {
+  saveOverlay,
+  loadOverlay,
+  listOverlays
+};

package/dist/{chunk-BRPU7AQC.js → chunk-A2I76FTA.js}

@@ -30,8 +30,20 @@ function writeLocalState(stackName, state) {
   writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf-8");
   renameSync(tmp, dest);
 }
+function localStateToConnectionInfo(state) {
+  return {
+    host: state.sshHost,
+    port: state.sshPort,
+    user: state.sshUser,
+    privateKeyPath: state.privateKeyPath,
+    knownHostsPath: state.knownHostsPath
+  };
+}
 
 export {
+  stateDir,
+  statePath,
   readLocalState,
-  writeLocalState
+  writeLocalState,
+  localStateToConnectionInfo
 };

package/dist/{chunk-LU63NZD3.js → chunk-JCUZU5BH.js}

@@ -2,12 +2,15 @@
 import {
   validatePlan
 } from "./chunk-YTH4L2GN.js";
+import {
+  saveOverlay
+} from "./chunk-6ZFIFDBJ.js";
 import {
   resolveSecrets
 } from "./chunk-BOPSG2LI.js";
 import {
   buildContext
-} from "./chunk-ACYJBSLJ.js";
+} from "./chunk-JDN6PLH2.js";
 import {
   atomicWriteConfig,
   deepMerge,
@@ -106,6 +109,7 @@ async function applyConfigOverlay(plan, outputs, ctx, signal) {
     });
     await atomicWriteConfig(session, merged, signal);
     await restartGateway(session, signal);
+    saveOverlay(plan.spec.stackName, configOverlay, plan.spec.secrets ?? []);
   } finally {
     session.close();
   }

package/dist/{chunk-ACYJBSLJ.js → chunk-JDN6PLH2.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   readLocalState
-} from "./chunk-BRPU7AQC.js";
+} from "./chunk-A2I76FTA.js";
 import {
   getConfigDir,
   requireConfig

package/dist/{chunk-QJ6ERXHN.js → chunk-LVIIYY27.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildContext
-} from "./chunk-ACYJBSLJ.js";
+} from "./chunk-JDN6PLH2.js";
 import {
   acquireSession,
   drainPool

package/dist/chunk-OIGTOLB3.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// src/cli/mcp-apps.ts
+import { execSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import path from "path";
+import os from "os";
+var MCP_APPS = [
+  {
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    configPath: () => process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json") : path.join(os.homedir(), ".config", "Claude", "claude_desktop_config.json"),
+    isInstalled: () => existsSync(
+      process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support", "Claude") : path.join(os.homedir(), ".config", "Claude")
+    )
+  },
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    configPath: () => path.join(os.homedir(), ".claude.json"),
+    isInstalled: () => {
+      if (existsSync(path.join(os.homedir(), ".claude.json"))) return true;
+      try {
+        execSync("claude --version", { stdio: "ignore" });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    configPath: () => path.join(os.homedir(), ".cursor", "mcp.json"),
+    isInstalled: () => existsSync(path.join(os.homedir(), ".cursor"))
+  },
+  {
+    id: "windsurf",
+    name: "Windsurf",
+    configPath: () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json"),
+    isInstalled: () => existsSync(path.join(os.homedir(), ".codeium", "windsurf"))
+  },
+  {
+    id: "vscode",
+    name: "VS Code",
+    configPath: () => process.platform === "linux" ? path.join(os.homedir(), ".config", "Code", "User", "mcp.json") : path.join(os.homedir(), "Library", "Application Support", "Code", "User", "mcp.json"),
+    isInstalled: () => existsSync(
+      process.platform === "linux" ? path.join(os.homedir(), ".config", "Code") : path.join(os.homedir(), "Library", "Application Support", "Code")
+    )
+  },
+  {
+    id: "zed",
+    name: "Zed",
+    configPath: () => path.join(os.homedir(), ".config", "zed", "settings.json"),
+    isInstalled: () => existsSync(path.join(os.homedir(), ".config", "zed")),
+    configKey: "context_servers",
+    entryExtra: { type: "stdio" }
+  }
+];
+function buildMcpEntry() {
+  try {
+    const bin = execSync("which clawops", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (bin) return { command: bin, args: ["mcp", "serve", "--read-only"], resolved: true };
+  } catch {
+  }
+  return { command: "clawops", args: ["mcp", "serve", "--read-only"], resolved: false };
+}
+function writeAppConfigs(apps, entry) {
+  return apps.map((app) => {
+    const cfgPath = app.configPath();
+    try {
+      let config = {};
+      if (existsSync(cfgPath)) {
+        try {
+          config = JSON.parse(readFileSync(cfgPath, "utf-8"));
+        } catch {
+        }
+      }
+      mkdirSync(path.dirname(cfgPath), { recursive: true });
+      const key = app.configKey ?? "mcpServers";
+      const servers = config[key] ?? {};
+      servers["clawops"] = { ...entry, ...app.entryExtra ?? {} };
+      config[key] = servers;
+      writeFileSync(cfgPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      return { app, configPath: cfgPath, ok: true };
+    } catch (err) {
+      return { app, configPath: cfgPath, ok: false, error: err.message };
+    }
+  });
+}
+
+export {
+  MCP_APPS,
+  buildMcpEntry,
+  writeAppConfigs
+};

package/dist/{chunk-QMXM2SMO.js → chunk-ZDPBBYYV.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-YTH4L2GN.js";
 import {
   buildContext
-} from "./chunk-ACYJBSLJ.js";
+} from "./chunk-JDN6PLH2.js";
 import {
   getConfig
 } from "./chunk-CX5SL5HP.js";
@@ -45,7 +45,7 @@ async function generatePlan(intent, _opts) {
       "plan/apply is not supported for the local provider. Use `clawops up` directly."
     );
   }
-  const { version } = await import("./package-3JZ767DN.js");
+  const { version } = await import("./package-AFUTH62F.js");
   const config = getConfig();
   const instanceType = intent.instanceType ?? "small";
   const openclawVersion = intent.openclawVersion ?? "latest";