@muxoai/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muxo AI, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @muxoai/cli
+
+**One key. One file. Your agent's entire toolkit.**
+
+The Muxo CLI is a thin client for the [Muxo runtime](https://api.muxo.ai) — a
+declarative `muxo.yaml` manifest plus a managed runtime that gives AI agents and
+developers unified access to web intelligence, LLMs, compute, and 60+ cloud
+services behind a single key and a single bill.
+
+## Install
+
+```bash
+npm install -g @muxoai/cli
+```
+
+## Quickstart
+
+```bash
+export MUXO_KEY=mk_test_...              # free test key, or: muxo login
+export MUXO_API_BASE=https://api.muxo.ai/v1
+
+muxo init "scrape hacker news every hour and store titles"
+muxo validate && muxo plan && muxo apply
+muxo run hn-scraper --param max_items=3
+muxo logs && muxo steps <instanceId>
+```
+
+## Commands
+
+```
+muxo init [intent]         Scaffold muxo.yaml (from intent string or interactive)
+muxo validate              Schema + catalog validation
+muxo plan                  Server-side diff → ordered op list
+muxo apply                 Push manifest, snapshot version
+muxo add <bundle>          Append a bundle stanza
+muxo run <workflow>        Execute a workflow one-shot
+muxo status                Project, bundles, budget
+muxo keys list|create|rotate|revoke
+muxo credits balance|packs|buy <pack>
+muxo rollback [version]    Re-apply a previous manifest snapshot
+muxo logs [workflow]       Execution history
+muxo steps <instanceId>    Per-step log for one execution
+muxo login                 Store your key in the OS keychain
+muxo mcp                   Stdio MCP proxy for agents
+```
+
+Global flags: `--json`, `--quiet`, `--debug`.
+
+## Agent-first
+
+Point any MCP client at `https://api.muxo.ai/mcp` (Bearer auth), or use the
+stdio proxy: `MUXO_KEY=mk_... muxo mcp`.
+
+## License
+
+MIT © Muxo AI, LLC

package/dist/index.js

@@ -0,0 +1,1127 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { access, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+// src/lib/templates.ts
+import { stringify } from "yaml";
+var KNOWN_BUNDLES = [
+  { name: "web-intel", capabilities: ["web.search", "web.scrape", "web.extract"] },
+  { name: "web-scale", capabilities: ["web.crawl", "web.monitor"] },
+  { name: "llm", capabilities: ["llm.chat", "llm.embed"] },
+  { name: "voice", capabilities: ["llm.tts"] },
+  { name: "browser", capabilities: ["browser.drive"] },
+  { name: "compute", capabilities: ["compute.sandbox", "compute.container"] },
+  { name: "deploy", capabilities: ["deploy.site", "deploy.container", "deploy.edge"] },
+  { name: "domains", capabilities: ["domains.register", "dns.manage"] },
+  { name: "storage", capabilities: ["storage.object", "vector.search"] },
+  { name: "ops", capabilities: ["observability.log", "queue.emit", "email.send"] }
+];
+function findBundle(name) {
+  return KNOWN_BUNDLES.find((b) => b.name === name);
+}
+var webIntel = {
+  bundles: { "web-intel": { capabilities: ["web.search", "web.scrape", "web.extract"] } }
+};
+var llm = {
+  bundles: { llm: { capabilities: ["llm.chat", "llm.embed"] } }
+};
+var priceRadar = {
+  bundles: { "web-intel": { capabilities: ["web.search", "web.scrape", "web.extract"] } },
+  workflows: {
+    "daily-prices": {
+      on: { schedule: "0 6 * * *" },
+      steps: [
+        { search: { cap: "web.search", query: "competitor pricing", into: "results" } },
+        { scrape: { cap: "web.scrape", urls: "${results.urls}", into: "pages" } },
+        {
+          extract: {
+            cap: "web.extract",
+            from: "pages",
+            schema: { product: "str", price: "num" },
+            into: "prices"
+          }
+        },
+        { store: { cap: "db.write", into: "stack.database.main.prices" } }
+      ]
+    }
+  },
+  stack: {
+    database: { main: { provider: "neon", service: "postgres" } }
+  }
+};
+function slugify(name) {
+  const slug2 = name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+  return slug2.length >= 3 ? slug2 : `${slug2}-project`.slice(0, 40);
+}
+function detectSchedule(intent) {
+  const lower = intent.toLowerCase();
+  if (/\bevery (hour|hr)\b|\bhourly\b/.test(lower)) return "0 * * * *";
+  if (/\bevery (\d+) hours?\b/.test(lower)) {
+    const n = Math.max(1, Math.min(23, parseInt(/\bevery (\d+) hours?\b/.exec(lower)?.[1] ?? "1", 10)));
+    return `0 */${n} * * *`;
+  }
+  if (/\bevery (\d+) minutes?\b/.test(lower)) {
+    const n = Math.max(1, Math.min(59, parseInt(/\bevery (\d+) minutes?\b/.exec(lower)?.[1] ?? "15", 10)));
+    return `*/${n} * * * *`;
+  }
+  if (/\bdaily\b|\bevery day\b|\b(?:each|every) morning\b/.test(lower)) return "0 6 * * *";
+  if (/\bweekly\b|\bevery week\b/.test(lower)) return "0 6 * * 1";
+  return void 0;
+}
+function matchTemplate(intent) {
+  const lower = intent.toLowerCase();
+  const bundles = {};
+  let workflows;
+  let stack;
+  let schedule = detectSchedule(intent);
+  if (/\bprice|pricing\b/.test(lower)) {
+    return priceRadar;
+  }
+  if (/track|monitor|scrape|search|extract|crawl|web|news|hacker|hn/.test(lower)) {
+    Object.assign(bundles, webIntel.bundles);
+  }
+  if (/chat|llm|summar|embed|\bai\b/.test(lower)) {
+    Object.assign(bundles, llm.bundles);
+  }
+  if (/store|database|db|postgres|save\b/.test(lower)) {
+    stack = { database: { main: { provider: "neon", service: "postgres" } } };
+  }
+  if (schedule !== void 0 && Object.keys(bundles).length > 0) {
+    const topic = (lower.match(/[a-z][a-z-]{3,}/)?.[0] ?? "watch").slice(0, 20);
+    workflows = {
+      [`${topic.replace(/-+$/, "")}-watch`]: {
+        on: { schedule },
+        steps: [
+          { search: { cap: "web.search", query: intent.slice(0, 80), limit: 3, into: "results" } },
+          { log: { cap: "observability.log", level: "info", message: "found ${results.count} results" } }
+        ]
+      }
+    };
+  }
+  if (Object.keys(bundles).length === 0) return { bundles: {} };
+  return { bundles, workflows, stack };
+}
+function renderManifest(project, description, tpl) {
+  const doc = {
+    muxo: "0.1",
+    project,
+    ...description ? { description } : {}
+  };
+  if (tpl.stack && Object.keys(tpl.stack).length > 0) doc.stack = tpl.stack;
+  if (Object.keys(tpl.bundles).length > 0) doc.bundles = tpl.bundles;
+  if (tpl.workflows) doc.workflows = tpl.workflows;
+  doc.budget = { monthly_credits: 1e3, hard_stop: true };
+  return stringify(doc);
+}
+
+// src/lib/output.ts
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function exitCodeFor(env) {
+  if (env.ok) return 0;
+  return env.error.code === "forbidden" ? 2 : 1;
+}
+function printError(env) {
+  if (env.ok) return;
+  console.error(`error: ${env.error.code}: ${env.error.message}`);
+  if (env.error.retry_after_ms !== void 0) {
+    console.error(`retry after ${env.error.retry_after_ms}ms`);
+  }
+}
+function humanData(env) {
+  if (!env.ok) return;
+  if (typeof env.data === "string") {
+    console.log(env.data);
+    return;
+  }
+  printJson(env.data);
+}
+function renderEnvelope(env, json, human) {
+  if (json) {
+    printJson(env);
+    return exitCodeFor(env);
+  }
+  if (!env.ok) {
+    printError(env);
+    return exitCodeFor(env);
+  }
+  if (human) {
+    human(env.data);
+  } else {
+    humanData(env);
+  }
+  return 0;
+}
+function info(msg, opts) {
+  if (opts.json || opts.quiet) return;
+  console.log(msg);
+}
+function nextSteps(msgs, opts) {
+  if (opts.json || opts.quiet) return;
+  console.error("Next steps:");
+  for (const m of msgs) console.error(`  ${m}`);
+}
+
+// src/commands/init.ts
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function init(intent, opts) {
+  if (await exists("muxo.yaml")) {
+    console.error("error: muxo.yaml already exists in this directory");
+    return 1;
+  }
+  const it = intent ?? "";
+  const tpl = matchTemplate(it);
+  const project = slugify(basename(process.cwd()));
+  const text = renderManifest(project, it, tpl);
+  await writeFile("muxo.yaml", text, "utf8");
+  info("wrote muxo.yaml", opts);
+  nextSteps(["muxo validate", "muxo plan", "muxo apply", "muxo run <workflow>  # or wait for the cron schedule", "muxo logs             # watch executions"], opts);
+  return 0;
+}
+
+// src/lib/config.ts
+import { readFile as readFile2 } from "node:fs/promises";
+
+// src/lib/keychain.ts
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, unlink, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var SERVICE = "muxo";
+var ACCOUNT = "muxo-key";
+var KEY_FILE = join(homedir(), ".muxo", "key");
+async function keychainGet() {
+  if (process.platform === "darwin") {
+    try {
+      const { stdout } = await run("security", [
+        "find-generic-password",
+        "-s",
+        SERVICE,
+        "-a",
+        ACCOUNT,
+        "-w"
+      ]);
+      const key = stdout.trim();
+      if (key) return key;
+    } catch {
+    }
+  }
+  try {
+    const key = (await readFile(KEY_FILE, "utf8")).trim();
+    return key || void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function keychainSet(key) {
+  if (process.platform === "darwin") {
+    try {
+      await run("security", [
+        "add-generic-password",
+        "-U",
+        "-s",
+        SERVICE,
+        "-a",
+        ACCOUNT,
+        "-w",
+        key
+      ]);
+      return "keychain";
+    } catch {
+    }
+  }
+  await mkdir(dirname(KEY_FILE), { recursive: true });
+  await writeFile2(KEY_FILE, `${key}
+`, { mode: 384 });
+  await chmod(KEY_FILE, 384);
+  return "file";
+}
+
+// src/lib/config.ts
+var DEFAULT_BASE_URL = "https://api.muxo.ai/v1";
+var LOCAL_BASE_URL = "http://localhost:8787/v1";
+function baseUrl(local) {
+  if (local) return LOCAL_BASE_URL;
+  return process.env.MUXO_API_BASE || DEFAULT_BASE_URL;
+}
+async function resolveKey() {
+  if (process.env.MUXO_KEY) return process.env.MUXO_KEY;
+  return keychainGet();
+}
+var MANIFEST_FILES = ["muxo.yaml", "muxo.muxo", ".muxo/muxo.yaml"];
+async function readManifestText() {
+  for (const file of MANIFEST_FILES) {
+    try {
+      return await readFile2(file, "utf8");
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+
+// src/commands/validate.ts
+import { validateManifest as coreValidate } from "@muxoai/core";
+
+// src/lib/validate.ts
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+var slug = z.string().regex(/^[a-z0-9-]{3,40}$/);
+var stackEntry = z.object({
+  provider: z.string().min(1),
+  service: z.string().min(1)
+}).passthrough();
+var routing = z.object({
+  prefer: z.enum(["cost", "latency", "reliability"]).optional(),
+  fallback: z.array(z.string()).optional(),
+  locked: z.boolean().optional()
+});
+var bundle = z.object({
+  capabilities: z.array(z.string().min(1)).min(1),
+  routing: routing.optional()
+});
+var workflow = z.object({
+  on: z.object({
+    schedule: z.string().optional(),
+    event: z.string().optional()
+  }).optional(),
+  params: z.record(
+    z.object({
+      type: z.enum(["string", "number", "boolean"]),
+      required: z.boolean().optional(),
+      default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+      description: z.string().optional()
+    })
+  ).optional(),
+  retries: z.number().int().min(0).max(10).optional(),
+  timeout_seconds: z.number().int().min(1).max(3600).optional(),
+  on_error: z.enum(["halt", "continue"]).optional(),
+  steps: z.array(z.record(z.unknown())).optional()
+});
+var manifestSchema = z.object({
+  muxo: z.string().regex(/^\d+\.\d+(\.\d+)?$/),
+  project: slug,
+  description: z.string().optional(),
+  env: z.record(
+    z.string().regex(/^[A-Z_][A-Z0-9_]*$/, "env keys must be UPPER_SNAKE_CASE"),
+    z.union([z.string(), z.number(), z.boolean()])
+  ).optional(),
+  stack: z.record(z.record(stackEntry)).optional(),
+  bundles: z.record(bundle).optional(),
+  budget: z.object({
+    monthly_credits: z.number().int().positive(),
+    hard_stop: z.boolean().optional(),
+    per_workflow: z.record(z.number().int().positive()).optional()
+  }).optional(),
+  workflows: z.record(workflow).optional()
+}).strict();
+function validateManifest(text) {
+  let doc;
+  try {
+    doc = parseYaml(text);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return [{ path: "", message: `yaml parse error: ${message}` }];
+  }
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    return [{ path: "", message: "manifest must be a YAML mapping" }];
+  }
+  const issues = [];
+  const parsed = manifestSchema.safeParse(doc);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      issues.push({ path: issue.path.join("."), message: issue.message });
+    }
+  }
+  const m = doc;
+  if (typeof m.muxo === "string") {
+    const major = Number.parseInt(m.muxo.split(".")[0] ?? "", 10);
+    if (Number.isFinite(major) && major > 0) {
+      issues.push({
+        path: "muxo",
+        message: `unsupported format version "${m.muxo}"; upgrade your muxo client to read v${major} manifests`
+      });
+    }
+  }
+  if (m.bundles && typeof m.bundles === "object" && !Array.isArray(m.bundles)) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const [name, b] of Object.entries(m.bundles)) {
+      const caps = b?.capabilities;
+      if (!Array.isArray(caps)) continue;
+      for (const cap of caps) {
+        if (typeof cap !== "string") continue;
+        const owner = seen.get(cap);
+        if (owner) {
+          issues.push({
+            path: `bundles.${name}.capabilities`,
+            message: `capability "${cap}" already declared in bundle "${owner}"`
+          });
+        } else {
+          seen.set(cap, name);
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+// src/commands/validate.ts
+async function validate(opts) {
+  const text = await readManifestText();
+  if (text === void 0) {
+    const err = [{ path: "", message: "no muxo.yaml found in this directory" }];
+    if (opts.json) printJson(err);
+    else console.error(`error: ${err[0].message}`);
+    return 1;
+  }
+  const issues = [
+    ...coreValidate(text).errors.map((e) => ({ path: e.path, message: e.message + (e.hint ? ` (${e.hint})` : "") })),
+    ...validateManifest(text)
+  ];
+  if (opts.json) {
+    printJson(issues);
+  } else if (issues.length === 0) {
+    if (!opts.quiet) console.log("muxo.yaml is valid");
+  } else {
+    for (const issue of issues) {
+      console.error(`error: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`);
+    }
+  }
+  return issues.length > 0 ? 1 : 0;
+}
+
+// src/lib/api.ts
+async function request(opts, method, path, body) {
+  if (opts.debug) {
+    console.error(`muxo: ${method} ${opts.baseUrl}${path}`);
+  }
+  let res;
+  try {
+    res = await fetch(`${opts.baseUrl}${path}`, {
+      method,
+      headers: {
+        ...opts.key ? { authorization: `Bearer ${opts.key}` } : {},
+        "content-type": "application/json"
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: {
+        code: "internal",
+        message: `network error reaching ${opts.baseUrl}${path}: ${reason}. If this is your first run, set MUXO_API_BASE to your runtime URL (e.g. export MUXO_API_BASE=https://api.muxo.ai/v1)`
+      }
+    };
+  }
+  try {
+    return await res.json();
+  } catch {
+    return {
+      ok: false,
+      error: { code: "internal", message: `muxo returned HTTP ${res.status} with a non-JSON body` }
+    };
+  }
+}
+function makeApi(opts) {
+  return {
+    get: (path) => request(opts, "GET", path),
+    post: (path, body) => request(opts, "POST", path, body),
+    put: (path, body) => request(opts, "PUT", path, body),
+    del: (path) => request(opts, "DELETE", path)
+  };
+}
+
+// src/commands/plan.ts
+async function plan(opts) {
+  const text = await readManifestText();
+  if (text === void 0) {
+    console.error("error: no muxo.yaml found in this directory");
+    return 1;
+  }
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const env = await api.post("/plan", { yaml: text });
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const ops = data?.ops;
+    if (Array.isArray(ops)) {
+      if (ops.length === 0) {
+        console.log("no changes \u2014 manifest matches the deployed state");
+        return;
+      }
+      const ICONS = {
+        provision: "+",
+        register_bundle: "+",
+        register_workflow: "+",
+        upgrade: "~",
+        downgrade: "~",
+        deprovision: "-",
+        noop: "!"
+      };
+      ops.forEach((op, i) => {
+        const icon = ICONS[op.kind] ?? "\xB7";
+        const label = op.detail !== void 0 && op.detail !== "" ? `${op.ref}: ${op.detail}` : op.ref;
+        console.log(`${i + 1}. ${icon} ${label}`);
+      });
+      const removes = ops.filter((o) => o.kind === "deprovision").length;
+      if (removes > 0) console.log(`
+\u26A0 ${removes} deprovision op(s) \u2014 apply will remove these resources`);
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+  });
+}
+async function apply(opts) {
+  const text = await readManifestText();
+  if (text === void 0) {
+    console.error("error: no muxo.yaml found in this directory");
+    return 1;
+  }
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const env = await api.put("/manifest", { yaml: text });
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const d = data;
+    const version = d?.version !== void 0 ? ` version ${d.version}` : "";
+    const ops = Array.isArray(d?.ops) ? ` (${d.ops.length} ops)` : "";
+    console.log(`applied${version}${ops}`);
+    if (Array.isArray(d?.ops)) {
+      d.ops.forEach((op, i) => {
+        const label = typeof op === "string" ? op : JSON.stringify(op);
+        console.log(`  ${i + 1}. ${label}`);
+      });
+    }
+  });
+}
+
+// src/commands/add.ts
+import { readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
+import { parse as parseYaml2, stringify as stringify2 } from "yaml";
+async function add(bundleName, opts) {
+  const def = findBundle(bundleName);
+  if (!def) {
+    const known = KNOWN_BUNDLES.map((b) => b.name).join(", ");
+    console.error(`error: unknown bundle "${bundleName}" (known: ${known})`);
+    return 1;
+  }
+  let text;
+  try {
+    text = await readFile3("muxo.yaml", "utf8");
+  } catch {
+    console.error("error: no muxo.yaml found in this directory");
+    return 1;
+  }
+  let doc;
+  try {
+    doc = parseYaml2(text);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`error: yaml parse error: ${msg}`);
+    return 1;
+  }
+  if (!doc || typeof doc !== "object") {
+    console.error("error: muxo.yaml must be a YAML mapping");
+    return 1;
+  }
+  const bundles = doc.bundles ?? {};
+  if (bundles[def.name]) {
+    console.error(`error: bundle "${def.name}" already exists in muxo.yaml`);
+    return 1;
+  }
+  bundles[def.name] = { capabilities: def.capabilities };
+  doc.bundles = bundles;
+  await writeFile3("muxo.yaml", stringify2(doc), "utf8");
+  if (!opts.json && !opts.quiet) {
+    console.log(`added bundle ${def.name} (${def.capabilities.join(", ")})`);
+  }
+  return 0;
+}
+
+// src/commands/run.ts
+function printSteps(data) {
+  const d = data;
+  if (d?.execution_id !== void 0) console.log(`execution ${String(d.execution_id)}`);
+  if (Array.isArray(d?.steps)) {
+    for (const step of d.steps) {
+      const name = typeof step?.name === "string" ? step.name : "step";
+      const status2 = typeof step?.status === "string" ? step.status : JSON.stringify(step);
+      console.log(`  ${name}: ${status2}`);
+      if (step?.error !== void 0) console.log(`    ${JSON.stringify(step.error)}`);
+    }
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+function coerceParam(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value !== "" && !Number.isNaN(Number(value))) return Number(value);
+  return value;
+}
+function parseParams(raw) {
+  const params = {};
+  for (const entry of raw ?? []) {
+    const eq = entry.indexOf("=");
+    if (eq === -1) throw new Error(`--param expects key=value, got "${entry}"`);
+    params[entry.slice(0, eq)] = coerceParam(entry.slice(eq + 1));
+  }
+  return params;
+}
+async function run2(workflow2, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const params = parseParams(opts.param);
+  const env = await api.post(`/workflows/${workflow2}/run`, Object.keys(params).length > 0 ? { params } : {});
+  const instanceId = (env.ok ? env.data : void 0)?.instanceId;
+  const result = renderEnvelope(env, !!opts.json, printSteps);
+  if (!opts.json && typeof instanceId === "string" && instanceId.length > 0) {
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 2e3));
+      const execs = await api.get(`/workflows/${encodeURIComponent(workflow2)}/executions`);
+      const row = execs.data?.executions?.find((e) => e.id === instanceId);
+      if (row === void 0 || row.status !== "running") break;
+    }
+    const steps = await api.get(`/executions/${encodeURIComponent(instanceId)}/steps`);
+    const rows = steps.data?.steps ?? [];
+    if (rows.length > 0) {
+      console.log("steps:");
+      for (const s of rows) {
+        const mark = s.status === "ok" ? "\u2713" : "\u2717";
+        const err = s.error ? ` \u2014 ${s.error}` : "";
+        console.log(`  ${mark} ${s.step} (${s.capability}) \u2192 ${s.provider}, ${s.credits} credits, ${s.latency_ms}ms${err}`);
+      }
+    }
+  }
+  return result;
+}
+async function status(opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const env = await api.get("/status");
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const d = data;
+    if (d && typeof d === "object" && !Array.isArray(d)) {
+      if (d.project !== void 0) console.log(`project: ${String(d.project)}`);
+      if (d.version !== void 0) console.log(`version: ${String(d.version)}`);
+      if (d.bundles !== void 0) {
+        const bundles = Array.isArray(d.bundles) ? d.bundles.map(String).join(", ") : Object.keys(d.bundles).join(", ");
+        console.log(`bundles: ${bundles || "(none)"}`);
+      }
+      if (Array.isArray(d.workflows)) console.log(`workflows: ${d.workflows.map(String).join(", ") || "(none)"}`);
+      if (d.budget !== void 0) console.log(`budget: ${JSON.stringify(d.budget)}`);
+      if (d.drift !== void 0) console.log(`drift: ${JSON.stringify(d.drift)}`);
+      return;
+    }
+    console.log(JSON.stringify(data, null, 2));
+  });
+}
+async function rollback(version, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const body = version === void 0 ? {} : { version: Number(version) };
+  const env = await api.post("/rollback", body);
+  return renderEnvelope(env, !!opts.json, (data) => {
+    console.log(`rolled back to ${JSON.stringify(data)}`);
+  });
+}
+async function logs(workflow2, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const qs = workflow2 ? `?workflow=${encodeURIComponent(workflow2)}` : "";
+  const env = await api.get(`/workflows/${encodeURIComponent(workflow2 ?? "_all")}/executions${qs}`);
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const d = data;
+    if (Array.isArray(d?.executions)) {
+      for (const e of d.executions) {
+        const when = new Date(e.started_at).toISOString().slice(0, 19).replace("T", " ");
+        const err = e.error ? ` \u2014 ${e.error}` : "";
+        console.log(`${when}  ${e.workflow}  ${e.status}${err}`);
+        console.log(`  steps: muxo steps ${e.id}`);
+      }
+      return;
+    }
+    console.log(JSON.stringify(data, null, 2));
+  });
+}
+async function stepLogs(instanceId, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  const env = await api.get(`/executions/${encodeURIComponent(instanceId)}/steps`);
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const rows = data?.steps ?? [];
+    for (const s of rows) {
+      const mark = s.status === "ok" ? "\u2713" : "\u2717";
+      const err = s.error ? ` \u2014 ${s.error}` : "";
+      console.log(`${s.seq}. ${mark} ${s.step} (${s.capability}) \u2192 ${s.provider}, ${s.credits} credits, ${s.latency_ms}ms${err}`);
+    }
+  });
+}
+
+// src/commands/keys.ts
+async function keysCommand(action, id, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  if (action === "revoke" && !id) {
+    console.error("error: revoke requires a key id");
+    return 1;
+  }
+  if (action === "rotate" && !id) {
+    const listed = await api.get("/keys");
+    if (!listed.ok) return renderEnvelope(listed, !!opts.json);
+    const keys = listed.data ?? [];
+    const active = keys.find((k) => k?.revoked !== true);
+    if (active === void 0 || typeof active.id !== "string") {
+      console.error("error: no active key to rotate");
+      return 1;
+    }
+    id = active.id;
+  }
+  let env;
+  switch (action) {
+    case "list":
+      env = await api.get("/keys");
+      break;
+    case "create":
+      env = await api.post("/keys");
+      break;
+    case "rotate":
+      env = await api.post(`/keys/${id}/rotate`);
+      break;
+    case "revoke":
+      env = await api.del(`/keys/${id}`);
+      break;
+  }
+  if (env.ok && (action === "create" || action === "rotate") && !opts.json) {
+    const data = env.data;
+    if (data?.key !== void 0) {
+      const id2 = data.keyId ?? data.id;
+      console.log(`${action === "rotate" ? "rotated" : "created"} key ${id2 !== void 0 ? String(id2) : ""}`);
+      console.log(String(data.key));
+      console.log("store it now \u2014 it will not be shown again");
+      return 0;
+    }
+  }
+  return renderEnvelope(env, !!opts.json, (data) => {
+    if (Array.isArray(data)) {
+      for (const key of data) {
+        const k = key;
+        console.log(`${String(k?.id ?? "?")}${k?.revoked ? " (revoked)" : ""}`);
+      }
+      return;
+    }
+    printJson(data);
+  });
+}
+
+// src/commands/credits.ts
+async function creditsCommand(action, packId, opts) {
+  const api = makeApi({
+    baseUrl: baseUrl(opts.local),
+    key: await resolveKey(),
+    debug: opts.debug
+  });
+  if (action === "buy") {
+    if (!packId) {
+      console.error("error: buy requires a pack id (muxo credits packs)");
+      return 1;
+    }
+    const env2 = await api.post("/credits/checkout", { pack: packId });
+    return renderEnvelope(env2, !!opts.json, (data) => {
+      const d = data;
+      if (d?.url !== void 0) {
+        console.log(`checkout: ${d.url}`);
+        if (d.stubbed) console.log("(stub \u2014 set STRIPE_SECRET_KEY on the runtime for real checkout)");
+      }
+    });
+  }
+  const env = await api.get("/credits");
+  return renderEnvelope(env, !!opts.json, (data) => {
+    const d = data;
+    if (action === "packs") {
+      for (const p of d?.packs ?? []) {
+        console.log(`${p.id}  ${p.credits} credits  $${(p.price_cents / 100).toFixed(2)}`);
+      }
+      return;
+    }
+    console.log(`account: ${d?.account_id ?? "?"}`);
+    console.log(`balance: ${d?.balance_credits ?? 0} muxo credits`);
+    if (Array.isArray(d?.ledger) && d.ledger.length > 0) {
+      console.log("recent:");
+      for (const entry of d.ledger.slice(0, 10)) {
+        const when = new Date(entry.created_at).toISOString().slice(0, 19).replace("T", " ");
+        console.log(`  ${when}  ${entry.delta > 0 ? "+" : ""}${entry.delta}  ${entry.reason}`);
+      }
+    }
+  });
+}
+
+// src/commands/login.ts
+import { createInterface } from "node:readline";
+function promptHidden(promptText) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin });
+      rl.once("line", (line) => {
+        rl.close();
+        resolve(line.trim());
+      });
+      return;
+    }
+    process.stdout.write(promptText);
+    const wasRaw = process.stdin.isRaw ?? false;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    let buf = "";
+    const onData = (chunk) => {
+      for (const ch of chunk.toString("utf8")) {
+        if (ch === "\r" || ch === "\n") {
+          process.stdin.setRawMode(wasRaw);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          resolve(buf);
+          return;
+        }
+        if (ch === "\x7F" || ch === "\b") {
+          buf = buf.slice(0, -1);
+        } else if (ch === "") {
+          process.stdin.setRawMode(wasRaw);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          process.exit(130);
+        } else {
+          buf += ch;
+        }
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+async function login(opts) {
+  const key = await promptHidden("Paste your muxo key: ");
+  if (!key) {
+    console.error("error: no key provided");
+    return 1;
+  }
+  const where = await keychainSet(key);
+  if (where === "file") {
+    console.error("warning: keychain unavailable; key stored in ~/.muxo/key (chmod 600)");
+  }
+  info(where === "keychain" ? "key stored in OS keychain" : "key stored in ~/.muxo/key", opts);
+  nextSteps(["muxo status"], opts);
+  return 0;
+}
+
+// src/commands/mcp.ts
+import { createInterface as createInterface2 } from "node:readline";
+var STATIC_TOOLS = [
+  { name: "web_search", description: "Search the web. Inputs: query (required), limit?, freshness?." },
+  { name: "web_scrape", description: "Scrape URL(s) to markdown. Inputs: url or urls, formats?." },
+  { name: "web_extract", description: "Extract structured data from pages. Inputs: from (required), schema (required)." },
+  { name: "web_crawl", description: "Crawl a site. Inputs: url (required), depth?, limit?." },
+  { name: "web_monitor", description: "Poll a URL for change. Inputs: url (required), on: change." },
+  { name: "browser_drive", description: "Drive a browser session. Inputs: session (required), actions (required)." },
+  { name: "llm_chat", description: "Chat completion. Inputs: prompt (required), model?, context?." },
+  { name: "llm_embed", description: "Generate embeddings. Inputs: input (required)." },
+  { name: "llm_tts", description: "Text to speech. Inputs: text (required), voice?." },
+  { name: "compute_sandbox", description: "Run code in a sandbox. Inputs: code (required), runtime?, timeout?." },
+  { name: "kv_store", description: "Key-value store. Inputs: key (required), value (to write) or get (to read)." },
+  { name: "storage_object", description: "Object storage. Inputs: key (required), file (write) or get (read)." },
+  { name: "vector_search", description: "Vector search. Inputs: query (required), k?." },
+  { name: "email_send", description: "Send an email. Inputs: to, subject, body (all required)." },
+  { name: "observability_log", description: "Log an event. Inputs: level (required), message (required)." },
+  { name: "queue_emit", description: "Emit an event to a queue. Inputs: topic (required), payload (required)." }
+];
+function excluded(tool) {
+  return tool.startsWith("deploy_") || tool === "domains_register" || tool === "compute_container";
+}
+function toToolName(capability) {
+  return capability.replace(/\./g, "_");
+}
+function toCapability(tool) {
+  return tool.replace(/_/g, ".");
+}
+function toolShape(name, description) {
+  return { name, description, inputSchema: { type: "object" } };
+}
+async function fetchTools(baseUrl2, key) {
+  const api = makeApi({ baseUrl: baseUrl2, key });
+  const env = await api.get("/status");
+  if (!env.ok) return STATIC_TOOLS.map((t) => toolShape(t.name, t.description));
+  const data = env.data;
+  if (Array.isArray(data?.tools)) {
+    const tools = [];
+    for (const t of data.tools) {
+      if (typeof t === "string") {
+        tools.push(toolShape(toToolName(t), ""));
+        continue;
+      }
+      if (t !== null && typeof t === "object") {
+        const obj = t;
+        if (typeof obj.name !== "string") continue;
+        const name = obj.name.includes(".") ? toToolName(obj.name) : obj.name;
+        const description = typeof obj.description === "string" ? obj.description : "";
+        tools.push(toolShape(name, description));
+      }
+    }
+    const filtered = tools.filter((t) => !excluded(t.name));
+    return filtered.length > 0 ? filtered : STATIC_TOOLS.map((t) => toolShape(t.name, t.description));
+  }
+  if (Array.isArray(data?.capabilities)) {
+    const tools = data.capabilities.filter((c) => typeof c === "string").map((c) => toolShape(toToolName(c), "")).filter((t) => !excluded(t.name));
+    return tools.length > 0 ? tools : STATIC_TOOLS.map((t) => toolShape(t.name, t.description));
+  }
+  return STATIC_TOOLS.map((t) => toolShape(t.name, t.description));
+}
+function successResult(data, usage) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ data, usage }) }],
+    isError: false
+  };
+}
+function errorResult(error) {
+  const payload = {};
+  if (typeof error.code === "string") payload.code = error.code;
+  if (typeof error.message === "string") payload.message = error.message;
+  if (error.retry_after_ms !== void 0) payload.retry_after_ms = error.retry_after_ms;
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    isError: true
+  };
+}
+async function mcp(opts) {
+  const baseUrl2 = opts.local ? LOCAL_BASE_URL : process.env.MUXO_API_BASE || DEFAULT_BASE_URL;
+  const key = await resolveKey();
+  const api = makeApi({ baseUrl: baseUrl2, key });
+  let tools = null;
+  const write = (msg) => process.stdout.write(`${JSON.stringify(msg)}
+`);
+  const reply = (id, result) => write({ jsonrpc: "2.0", id, result });
+  const rpcError = (id, code, message) => write({ jsonrpc: "2.0", id, error: { code, message } });
+  async function handle(msg) {
+    const { id, method } = msg;
+    if (!method) {
+      if (id !== void 0) rpcError(id, -32600, "Invalid Request");
+      return;
+    }
+    if (method.startsWith("notifications/")) return;
+    switch (method) {
+      case "initialize": {
+        const params = msg.params ?? {};
+        const version = typeof params.protocolVersion === "string" ? params.protocolVersion : "2024-11-05";
+        reply(id, {
+          protocolVersion: version,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: "muxo", version: "0.1.0" }
+        });
+        return;
+      }
+      case "ping": {
+        reply(id, {});
+        return;
+      }
+      case "tools/list": {
+        if (!tools) tools = await fetchTools(baseUrl2, key);
+        reply(id, { tools });
+        return;
+      }
+      case "tools/call": {
+        const params = msg.params ?? {};
+        if (typeof params.name !== "string") {
+          rpcError(id, -32602, "Invalid params: name is required");
+          return;
+        }
+        const capability = toCapability(params.name);
+        const input = params.arguments ?? {};
+        const env = await api.post(`/capabilities/${capability}`, input);
+        reply(id, env.ok ? successResult(env.data, env.usage) : errorResult(env.error));
+        return;
+      }
+      default:
+        rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+  const rl = createInterface2({ input: process.stdin, terminal: false });
+  const pending = [];
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      rpcError(null, -32700, "Parse error");
+      return;
+    }
+    pending.push(handle(msg));
+  });
+  await new Promise((resolve) => rl.once("close", resolve));
+  await Promise.all(pending);
+  return 0;
+}
+
+// src/index.ts
+function flags(cmd) {
+  cmd.option("--json", "structured JSON output").option("--quiet", "suppress non-essential output").option("--debug", "log requests to stderr");
+}
+async function main() {
+  const program = new Command();
+  program.name("muxo").description("Muxo CLI \u2014 one key for your whole stack").version("0.1.0").addHelpText("after", `
+Examples:
+  muxo init "scrape hacker news every hour and store titles"
+  muxo validate && muxo plan && muxo apply
+  muxo run hn-scraper --param max_items=3
+  muxo logs && muxo steps <instanceId>
+
+Auth: export MUXO_KEY=mk_...   Endpoint: export MUXO_API_BASE=https://api.muxo.ai/v1
+Docs: https://api.muxo.ai/docs/quickstart`);
+  const initCmd = program.command("init [intent]");
+  flags(initCmd);
+  initCmd.description("Scaffold muxo.yaml from an intent string").action(async (intent, opts) => {
+    process.exitCode = await init(intent, opts);
+  });
+  const validateCmd = program.command("validate");
+  flags(validateCmd);
+  validateCmd.description("Validate muxo.yaml locally (structure, slug, budget)").action(async (opts) => {
+    process.exitCode = await validate(opts);
+  });
+  const planCmd = program.command("plan");
+  flags(planCmd);
+  planCmd.description("Server-side diff of muxo.yaml \u2192 ordered op list").action(async (opts) => {
+    process.exitCode = await plan(opts);
+  });
+  const applyCmd = program.command("apply");
+  flags(applyCmd);
+  applyCmd.description("Push manifest, execute plan, snapshot version").action(async (opts) => {
+    process.exitCode = await apply(opts);
+  });
+  const addCmd = program.command("add <bundle>");
+  flags(addCmd);
+  addCmd.description("Append a bundle stanza to muxo.yaml").action(async (bundle2, opts) => {
+    process.exitCode = await add(bundle2, opts);
+  });
+  const runCmd = program.command("run <workflow>");
+  flags(runCmd);
+  runCmd.option("--param <key=value>", "workflow parameter, e.g. --param count=3 (repeatable)", (v, prev) => [...prev, v], []);
+  runCmd.description("Execute a workflow one-shot").action(async (workflow2, opts) => {
+    process.exitCode = await run2(workflow2, opts);
+  });
+  const statusCmd = program.command("status");
+  flags(statusCmd);
+  statusCmd.description("Project health, bundles, budget state").action(async (opts) => {
+    process.exitCode = await status(opts);
+  });
+  const keys = program.command("keys");
+  flags(keys);
+  keys.description("Manage project keys");
+  const keysList = keys.command("list");
+  flags(keysList);
+  keysList.action(async (opts, cmd) => {
+    process.exitCode = await keysCommand("list", void 0, { ...cmd.parent.opts(), ...opts });
+  });
+  const keysCreate = keys.command("create");
+  flags(keysCreate);
+  keysCreate.action(async (opts, cmd) => {
+    process.exitCode = await keysCommand("create", void 0, { ...cmd.parent.opts(), ...opts });
+  });
+  const keysRotate = keys.command("rotate [id]");
+  flags(keysRotate);
+  keysRotate.action(async (id, opts, cmd) => {
+    process.exitCode = await keysCommand("rotate", id, { ...cmd.parent.opts(), ...opts });
+  });
+  const keysRevoke = keys.command("revoke <id>");
+  flags(keysRevoke);
+  keysRevoke.action(async (id, opts, cmd) => {
+    process.exitCode = await keysCommand("revoke", id, { ...cmd.parent.opts(), ...opts });
+  });
+  const credits = program.command("credits");
+  flags(credits);
+  credits.description("Account credit balance, packs, and top-up");
+  const creditsBalance = credits.command("balance");
+  flags(creditsBalance);
+  creditsBalance.action(async (opts, cmd) => {
+    process.exitCode = await creditsCommand("balance", void 0, { ...cmd.parent.opts(), ...opts });
+  });
+  const creditsPacks = credits.command("packs");
+  flags(creditsPacks);
+  creditsPacks.action(async (opts, cmd) => {
+    process.exitCode = await creditsCommand("packs", void 0, { ...cmd.parent.opts(), ...opts });
+  });
+  const creditsBuy = credits.command("buy <pack>");
+  flags(creditsBuy);
+  creditsBuy.action(async (pack, opts, cmd) => {
+    process.exitCode = await creditsCommand("buy", pack, { ...cmd.parent.opts(), ...opts });
+  });
+  const rollbackCmd = program.command("rollback [version]");
+  flags(rollbackCmd);
+  rollbackCmd.description("Re-apply a previous manifest snapshot").action(async (version, opts) => {
+    process.exitCode = await rollback(version, opts);
+  });
+  const logsCmd = program.command("logs [workflow]");
+  flags(logsCmd);
+  logsCmd.description("Fetch execution logs").action(async (workflow2, opts) => {
+    process.exitCode = await logs(workflow2, opts);
+  });
+  const stepsCmd = program.command("steps <instanceId>");
+  flags(stepsCmd);
+  stepsCmd.description("Per-step log for one execution (step, capability, provider, credits, error)").action(async (instanceId, opts) => {
+    process.exitCode = await stepLogs(instanceId, opts);
+  });
+  const loginCmd = program.command("login");
+  flags(loginCmd);
+  loginCmd.description("Store your muxo key in the OS keychain").action(async (opts) => {
+    process.exitCode = await login(opts);
+  });
+  const mcpCmd = program.command("mcp");
+  flags(mcpCmd);
+  mcpCmd.option("--local", "target local runtime (http://localhost:8787/v1)");
+  mcpCmd.description("Stdio MCP proxy wrapping the muxo API (SPEC \xA712)").action(async (opts) => {
+    process.exitCode = await mcp(opts);
+  });
+  await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@muxoai/cli",
+  "version": "0.1.0",
+  "description": "Muxo CLI: one key for your whole stack — scaffold, validate, apply, run, and monitor agent workflows.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "muxo": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muxoai/muxo.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://api.muxo.ai",
+  "bugs": {
+    "url": "https://github.com/muxoai/muxo/issues"
+  },
+  "keywords": [
+    "muxo",
+    "cli",
+    "agents",
+    "capabilities",
+    "ai"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --packages=external --log-level=warning",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@muxoai/core": "^0.1.0",
+    "commander": "^12.0.0",
+    "yaml": "^2.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.21.5",
+    "typescript": "^5.6.0"
+  }
+}