@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/commands/apps.js

@@ -0,0 +1,64 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo apps`: the workspace's apps, with their type, state, preview and live
+ * addresses, and what is live now. The slug is what `oalo deploy --app` takes.
+ */
+export async function apps(flags) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) {
+    console.error(`oalo apps needs a CLI token.\n\n${HOW_TO_CONNECT}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const ch = new OaloChannel({ url, token });
+  try {
+    await ch.connect();
+    const { apps: list = [] } = await ch.call("list_apps", {});
+    const rows = await Promise.all(
+      list.map(async (a) => {
+        let release = null;
+        let containers = null;
+        let incident = null;
+        try {
+          const r = await ch.call("get_release", { app_id: a.id, containers: true });
+          release = r?.release || null;
+          containers = r?.containers || null;
+          incident = r?.incident || null;
+        } catch {
+          /* no release yet */
+        }
+        return { ...a, release, containers, incident };
+      }),
+    );
+
+    if (flags.json) return void console.log(JSON.stringify(rows, null, 2));
+    if (!rows.length) return void console.log(`no apps in ${url}`);
+
+    for (const a of rows.sort((x, y) => String(x.slug).localeCompare(String(y.slug)))) {
+      const runtime = a.app_type === "server" ? `server/${a.config?.server_runtime || "node"}` : a.app_type;
+      console.log(`${a.slug}  ${dim(`${runtime}, ${a.status}${a.slug === cfg.appId ? ", linked" : ""}`)}`);
+      if (a.preview_hostname) console.log(dim(`  preview  https://${a.preview_hostname}/`));
+      const live = a.custom_hostname || a.prod_hostname;
+      if (a.release?.commit_hash) {
+        console.log(dim(`  live     https://${live}/  at ${String(a.release.commit_hash).slice(0, 8)}${a.release.launched_at ? `, ${String(a.release.launched_at).slice(0, 16).replace("T", " ")}` : ""}`));
+        if (a.incident) console.log(`  ! ${a.incident.title} (since ${String(a.incident.opened_at).slice(0, 16).replace("T", " ")}): oalo incidents --app ${a.slug}`);
+        // Each live process that isn't running, with Docker's status.
+        for (const c of (a.containers || []).filter((c) => !c.running)) {
+          console.log(`  ${c.process || "process"} isn't running: ${c.status || c.state}. oalo logs --app ${a.slug} --env prod shows why.`);
+        }
+      } else if (live) {
+        console.log(dim(`  live     not launched yet (oalo deploy --app ${a.slug} --env prod)`));
+      }
+    }
+  } catch (e) {
+    console.error(e.message);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}

package/src/commands/bots.js

@@ -0,0 +1,278 @@
+import { readFileSync } from "node:fs";
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { requireFeature } from "../server.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo bots`: the workspace's bots, and the data each can search.
+ *
+ *   oalo bots                                         list them
+ *   oalo bots knowledge <bot>                         what it can search, and what else could be attached
+ *   oalo bots knowledge <bot> --add <source> [--remove <source>]
+ *   oalo bots tools <bot> [--add <tool>] [--remove <tool>]   the tools it may call
+ *   oalo bots settings <bot>                          every setting and its value
+ *   oalo bots settings <bot> set key=value ... [--yes] [--dry-run]
+ *   oalo bots settings --explain [key]                what each setting does
+ *
+ * A source is a table made searchable with `oalo data vectorize`: its handle
+ * (`model:products`, `table:prod.faq`) or just its name when that's unique.
+ * A bot always searches its own knowledge base (documents) too. Bots are named
+ * by their public id (`bot_...`), as `oalo bots` prints it. The changes go
+ * through the same actions as the bot's Knowledge pane in the dashboard.
+ */
+export async function bots(flags, rest, opts = {}) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo bots needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  const sub = rest[1];
+  if (sub && !["knowledge", "settings", "tools"].includes(sub)) return fail(`unknown bots command: ${sub}\n\n${USAGE}`, 2);
+  if ((sub === "knowledge" || sub === "tools") && !rest[2]) return fail(USAGE, 2);
+  if (sub === "settings" && !rest[2] && !flags.explain) return fail(USAGE, 2);
+
+  if (!opts.channel) {
+    try {
+      await requireFeature(url, "knowledge", "oalo bots");
+    } catch (e) {
+      return fail(e.message, 1);
+    }
+  }
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    if (sub === "knowledge") return await knowledge(ch, rest[2], flags);
+    if (sub === "settings") return await settings(ch, rest.slice(2), flags);
+    if (sub === "tools") return await tools(ch, rest[2], flags);
+    return await list(ch, flags, url);
+  } catch (e) {
+    return fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+}
+
+const USAGE = [
+  "usage: oalo bots [--json]",
+  "       oalo bots knowledge <bot> [--add <source>] [--remove <source>] [--json]",
+  "       oalo bots tools <bot> [--add <tool>] [--remove <tool>] [--json]",
+  "       oalo bots settings <bot> [--json]",
+  "       oalo bots settings <bot> set key=value [key=value ...] [--yes] [--dry-run]",
+  "       oalo bots settings --explain [key]",
+].join("\n");
+
+async function list(ch, flags, url) {
+  const { bots: all = [] } = await ch.call("chat:bots:list", {});
+  if (flags.json) return void console.log(JSON.stringify(all.map(summary), null, 2));
+  if (!all.length) return void console.log(`no bots in ${url}`);
+
+  for (const b of all.sort((x, y) => String(x.name).localeCompare(String(y.name)))) {
+    console.log(`${b.public_bot_id}  ${b.name}  ${dim(b.status || "")}`);
+    if (Array.isArray(b.search_sources)) console.log(dim(`  searches: ${searches(b.search_sources)}`));
+  }
+  console.log(dim("\nAttach a table: oalo bots knowledge <bot> --add <source>. Make one searchable first: oalo data vectorize <table> --fields ..."));
+}
+
+const summary = (b) => ({ id: b.public_bot_id, name: b.name, status: b.status, search_sources: b.search_sources ?? null });
+const searches = (list) => (list.length ? `${list.join(", ")}, and its own knowledge base` : "its own knowledge base only");
+
+async function knowledge(ch, botId, flags) {
+  if (!/^bot_[A-Za-z0-9_-]+$/.test(botId)) return fail(`name the bot by its public id (bot_...), as \`oalo bots\` prints it (got ${botId})`, 2);
+
+  const [{ bot }, { sources: available = [] }] = await Promise.all([
+    ch.call("chat:bots:get", { id: botId }),
+    ch.call("chat:bots:search_sources_available", {}),
+  ]);
+  const attached = Array.isArray(bot.search_sources) ? bot.search_sources : [];
+  const adds = values(flags.add), removes = values(flags.remove);
+
+  let now = attached;
+  const notes = [];
+  if (adds.length || removes.length) {
+    const toAdd = adds.map((a) => resolve(a, available.map((s) => s.handle), "searchable table"));
+    const toRemove = removes.map((r) => resolve(r, attached, "attached table"));
+    for (const h of toAdd) if (attached.includes(h)) notes.push(`${h} was already attached`);
+    now = [...new Set([...attached.filter((h) => !toRemove.includes(h)), ...toAdd])];
+
+    if (now.join("\n") !== attached.join("\n")) {
+      const r = await ch.call("chat:bots:update_search_sources", { id: botId, search_sources: now });
+      now = Array.isArray(r?.bot?.search_sources) ? r.bot.search_sources : now;
+    }
+  }
+
+  if (flags.json) return void console.log(JSON.stringify({ bot: botId, name: bot.name, search_sources: now, available }, null, 2));
+
+  const added = now.filter((h) => !attached.includes(h)), removed = attached.filter((h) => !now.includes(h));
+  for (const h of added) console.log(`attached ${h} to ${bot.name}`);
+  for (const h of removed) console.log(`detached ${h} from ${bot.name}`);
+  for (const n of notes) console.log(dim(n));
+  if (adds.length || removes.length) {
+    if (!added.length && !removed.length) console.log(`no change: ${bot.name} searches the same tables`);
+    console.log("");
+  }
+
+  const about = new Map(available.map((s) => [s.handle, s.description]));
+  console.log(`${bot.name} (${botId}) searches its own knowledge base${now.length ? ", and:" : " only."}`);
+  for (const h of now) console.log(`  ${h}${about.get(h) ? dim(`  ${about.get(h)}`) : about.has(h) ? "" : dim("  (no longer vectorized: searched as nothing)")}`);
+
+  const others = available.filter((s) => !now.includes(s.handle));
+  if (others.length) {
+    console.log(dim(`\nCan also attach (--add):`));
+    for (const s of others) console.log(dim(`  ${s.handle}${s.description ? `  ${s.description}` : ""}`));
+  } else if (!available.length) {
+    console.log(dim("\nNo table is searchable yet: oalo data vectorize <table> --fields <field,...>"));
+  }
+}
+
+// ── tools ────────────────────────────────────────────────────────────────
+
+const TRANSPORTS = { app: "your app", http_webhook: "webhook", builtin: "built in", wasm: "code", container_mcp: "action" };
+
+// The same change as a toggle in the bot's Tools tab: the allowlist is every
+// tool on now, plus or minus these.
+async function tools(ch, botId, flags) {
+  if (!/^bot_[A-Za-z0-9_-]+$/.test(botId)) return fail(`name the bot by its public id (bot_...), as \`oalo bots\` prints it (got ${botId})`, 2);
+  const { tools: list = [] } = await ch.call("chat:bots:tools:list", { bot_id: botId });
+  const usable = list.filter((t) => t.enabled);
+  const adds = values(flags.add), removes = values(flags.remove);
+  const byName = (name) => {
+    const t = usable.find((x) => x.name === name);
+    if (!t) throw new Error(`${name} isn't one of this workspace's tools${list.some((x) => x.name === name) ? " that's on" : ""}. \`oalo bots tools ${botId}\` lists them.`);
+    return t;
+  };
+
+  let now = list;
+  if (adds.length || removes.length) {
+    const on = new Set(list.filter((t) => t.allowlisted).map((t) => t.id));
+    for (const n of adds) on.add(byName(n).id);
+    for (const n of removes) on.delete(byName(n).id);
+    await ch.call("chat:bots:tools:set_allowlist", { bot_id: botId, tool_ids: [...on] });
+    now = list.map((t) => ({ ...t, allowlisted: on.has(t.id) }));
+    for (const n of adds) console.log(`attached ${n}`);
+    for (const n of removes) console.log(`detached ${n}`);
+  }
+
+  if (flags.json) return void console.log(JSON.stringify(now.map((t) => ({ name: t.name, kind: t.transport, attached: !!t.allowlisted, enabled: t.enabled, description: t.description })), null, 2));
+  const row = (t) => `  ${t.name}  ${dim(`${TRANSPORTS[t.transport] || t.transport}${t.requires_authenticated_user ? ", signed-in users only" : ""}`)}`;
+  const attached = now.filter((t) => t.allowlisted && t.enabled), others = now.filter((t) => !t.allowlisted && t.enabled);
+  console.log(attached.length ? `${botId} can call:` : `${botId} has no tools attached.`);
+  attached.forEach((t) => console.log(row(t)));
+  if (others.length) {
+    console.log(dim(`\nCan also attach (--add):`));
+    others.forEach((t) => console.log(dim(row(t))));
+  }
+}
+
+// ── settings ─────────────────────────────────────────────────────────────
+
+async function settings(ch, args, flags) {
+  const [botId, verb, ...pairs] = args;
+
+  if (flags.explain) {
+    const { settings: spec } = await ch.call("chat:bots:settings", {});
+    const key = typeof flags.explain === "string" ? flags.explain : botId;
+    const pick = key ? spec.filter((s) => s.key === key || s.key.startsWith(`${key}.`) || s.group === key) : spec;
+    if (!pick.length) return fail(`no setting ${key}. \`oalo bots settings --explain\` lists them all.`, 2);
+    if (flags.json) return void console.log(JSON.stringify(pick, null, 2));
+    for (const s of pick) explain(s);
+    return;
+  }
+
+  if (!/^bot_[A-Za-z0-9_-]+$/.test(botId)) return fail(`name the bot by its public id (bot_...), as \`oalo bots\` prints it (got ${botId})`, 2);
+  if (verb && verb !== "set") return fail(`unknown settings command: ${verb}\n\n${USAGE}`, 2);
+
+  if (!verb) {
+    const r = await ch.call("chat:bots:settings", { id: botId });
+    if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+    return show(r);
+  }
+
+  if (!pairs.length) return fail(`say what to change: oalo bots settings ${botId} set key=value`, 2);
+  const changes = {};
+  for (const p of pairs) {
+    const i = p.indexOf("=");
+    if (i < 1) return fail(`${p}: write it as key=value`, 2);
+    let v = p.slice(i + 1);
+    if (v.startsWith("@")) {
+      try {
+        v = readFileSync(v.slice(1), "utf8");
+      } catch (e) {
+        return fail(`${p.slice(0, i)}: can't read ${v.slice(1)} (${e.code || e.message})`, 2);
+      }
+    }
+    changes[p.slice(0, i)] = v;
+  }
+
+  let r;
+  try {
+    r = await ch.call("chat:bots:settings:set", { id: botId, changes, confirm: flags.yes === true, dry_run: flags["dry-run"] === true });
+  } catch (e) {
+    if (e.code === "confirm") {
+      console.log(`${e.message}\n`);
+      printDiff(e.reply.diff);
+      return fail("\nNothing changed. Run it again with --yes to apply.", 1);
+    }
+    if (e.code === "invalid") return fail(`nothing changed:\n${e.reply.errors.map((m) => `  ${m}`).join("\n")}`, 2);
+    throw e;
+  }
+
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  if (!r.diff.length) return void console.log(`no change: ${r.bot.name} already has ${Object.keys(changes).length === 1 ? "that value" : "those values"}`);
+  console.log(r.dry_run ? `${r.bot.name} would change (nothing was saved):` : `${r.bot.name} (${r.bot.id}):`);
+  printDiff(r.diff);
+}
+
+function show(r) {
+  console.log(`${r.bot.name} (${r.bot.id}), ${r.bot.status}`);
+  const width = Math.max(...r.settings.map((s) => s.key.length));
+  for (const group of r.groups) {
+    const rows = r.settings.filter((s) => s.group === group);
+    if (!rows.length) continue;
+    console.log(`\n${group}`);
+    for (const s of rows) {
+      const v = format(s.value, s);
+      console.log(`  ${s.key.padEnd(width)}  ${s.is_default ? v : `${v}${dim(`  (default ${format(s.default, s)})`)}`}`);
+    }
+  }
+  console.log(dim("\nChange one: oalo bots settings <bot> set key=value. What each does: oalo bots settings --explain <key>."));
+}
+
+function explain(s) {
+  const values = s.type === "one of" ? s.values.join(" | ") : s.type === "number" ? `a number from ${s.values[0]} to ${s.values[1]}` : s.type === "segments" ? `Title=mode; ... (modes: ${s.values.join(", ")})` : s.type;
+  console.log(`${s.key}  ${dim(`[${s.group}]`)}`);
+  console.log(`  ${s.doc}`);
+  console.log(dim(`  values: ${values}${s.clear_word ? `, or ${s.clear_word}` : ""}. Default: ${format(s.default, s)}.${s.effect ? ` Changing it ${s.effect}.` : ""}`));
+  console.log("");
+}
+
+function printDiff(diff) {
+  for (const d of diff) console.log(`  ${d.key}: ${format(d.from, d)} -> ${format(d.to, d)}${d.effect ? dim(`  (${d.effect})`) : ""}`);
+}
+
+function format(v, s) {
+  if (v === null || v === undefined) return s?.clear_word || "(none)";
+  if (Array.isArray(v)) return v.length ? v.map((x) => (typeof x === "object" ? `${x.node}=${x.mode}` : x)).join(typeof v[0] === "object" ? "; " : ", ") : "(none)";
+  const t = String(v).replace(/\s+/g, " ");
+  return t.length > 60 ? `${t.slice(0, 57)}...` : t;
+}
+
+// `--add` may repeat or be comma-separated.
+const values = (v) => (v === undefined || v === true ? [] : [].concat(v).flatMap((x) => String(x).split(",")).map((s) => s.trim()).filter(Boolean));
+
+// A handle, or a bare name when exactly one handle ends in it.
+function resolve(name, handles, what) {
+  if (handles.includes(name)) return name;
+  const matches = handles.filter((h) => h.endsWith(`:${name}`) || h.endsWith(`.${name}`));
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) throw new Error(`${name} could be ${matches.join(" or ")}: say which`);
+  if (what === "searchable table") {
+    throw new Error(`${name} isn't a searchable table yet. Make it one first: oalo data vectorize ${name.replace(/^(model:|table:\w+\.)/, "")} --fields <field,...>`);
+  }
+  throw new Error(`${name} isn't attached to this bot`);
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/call.js

@@ -0,0 +1,179 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { requireFeature } from "../server.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo call <event> [json]` — the escape hatch.
+ *
+ * The build surface is ~442 channel events. Wrapping each as its own command
+ * would be a large surface to maintain for little gain, and the same reasoning
+ * kept the MCP tool set curated rather than 1:1. So: first-class commands for
+ * what you do often, and this for everything else.
+ *
+ * Org and user identity always come from the token, never from the params, so a
+ * call can only reach what the minting user can reach.
+ */
+
+/**
+ * What each namespace is for. The events themselves come from the server
+ * (`cli_api:events`, derived from its own handlers), so this only adds a
+ * description; a namespace missing here still lists. It is also the whole
+ * answer on a workspace too old to list its events.
+ */
+const NAMESPACES = [
+  ["chat", "bots, flows, personas, prompts, knowledge, test messages"],
+  ["loops", "automations: list, get, create, update, run_now, runs, triggers"],
+  ["marketing", "campaigns, ads, metrics, pipelines, cut editor"],
+  ["kg", "knowledge graph: search, focus, roots, rebuild, reset"],
+  ["imports", "CSV/SQL import, schema mapping, make_syncable"],
+  ["widgets", "widget definitions, assignment, links"],
+  ["crm", "contacts, tags, segments"],
+  ["commerce", "products, orders, subscriptions"],
+  ["booking", "appointment types, availability, bookings"],
+  ["documents", "invoices, proposals, contracts"],
+  ["reviews", "review requests and responses"],
+  ["conversations", "threads, assignment, autopilot"],
+  ["inbox", "unified inbox listing and triage"],
+  ["whatsapp", "channels, templates, sends"],
+  ["instagram", "connection and messaging"],
+  ["email", "strategies, sends, suppression"],
+  ["fn", "custom WASM functions: source, config, secrets, expose"],
+  ["jobs", "background job snapshot, retry, cancel"],
+  ["git", "definition repos: history, clone, push"],
+  ["reporting", "summaries and customer reports"],
+  ["usage", "LLM spend ledger"],
+  ["org_members", "team and access"],
+  ["apple", "native build config"],
+  ["stripe", "billing connection"],
+];
+
+const DESCRIBE = new Map(NAMESPACES);
+
+/**
+ * `oalo call --list [text]`: the events you may call, from the server. With no
+ * text, a count per namespace; with text, each matching event and the param
+ * shapes it accepts. Falls back to the static namespaces on an older box.
+ */
+async function list(flags, rest) {
+  const q = typeof flags.list === "string" ? flags.list : rest[1] || "";
+  const { url, token } = controlPlane(resolveConfig(flags));
+
+  let events = null;
+  if (url && token) {
+    try {
+      await requireFeature(url, "events", "oalo call --list");
+      const ch = new OaloChannel({ url, token });
+      try {
+        await ch.connect();
+        ({ events } = await ch.call("cli_api:events", { q }));
+      } finally {
+        ch.close();
+      }
+    } catch (e) {
+      console.error(dim(`${e.message}\nShowing the built-in namespace list instead.\n`));
+    }
+  }
+
+  if (!events) return printNamespaces();
+  if (flags.json) return void console.log(JSON.stringify(events, null, 2));
+
+  if (!events.length) {
+    console.log(`no events you can call match "${q}"`);
+    return;
+  }
+
+  if (q) {
+    for (const e of events) {
+      console.log(e.event);
+      for (const a of e.accepts) console.log(dim(`  ${a}`));
+    }
+    console.log(dim(`\n${events.length} event${events.length > 1 ? "s" : ""}. Each line under an event is one param shape it accepts.`));
+    return;
+  }
+
+  const counts = new Map();
+  for (const e of events) {
+    // A few old events have no namespace (answer_question, browse_media...).
+    const ns = e.event.includes(":") ? e.event.split(":")[0] : "(none)";
+    counts.set(ns, (counts.get(ns) || 0) + 1);
+  }
+  const names = [...counts.keys()].sort();
+  const w = Math.max(...names.map((n) => n.length));
+  console.log(`${events.length} events you can call, by namespace:\n`);
+  for (const ns of names) console.log(`  ${ns.padEnd(w)}  ${String(counts.get(ns)).padStart(3)}  ${DESCRIBE.get(ns) || ""}`);
+  console.log(`\nSee one namespace's events and params: oalo call --list loops:\nSearch: oalo call --list template`);
+}
+
+function printNamespaces() {
+  console.log("Event names look like <namespace>:<verb>, e.g. loops:run_now.\n");
+  const w = Math.max(...NAMESPACES.map(([n]) => n.length));
+  for (const [ns, desc] of NAMESPACES) console.log(`  ${ns.padEnd(w)}  ${desc}`);
+  console.log(
+    "\nParams go in as JSON. Org and user come from your token, never the params:\n" +
+      `  oalo call loops:run_now '{"name":"Nurture"}'\n` +
+      `  oalo call chat:bots:list\n` +
+      `  oalo call jobs:snapshot | jq .\n\n` +
+      "An unknown event returns a clean error naming what you sent, so guessing\n" +
+      "a verb is cheap. Anything the dashboard does has an event behind it.",
+  );
+}
+
+export async function call(flags, rest) {
+  if (flags.list || flags.namespaces) {
+    await list(flags, rest);
+    return;
+  }
+
+  const event = rest[1];
+  if (!event) {
+    console.error("usage: oalo call <event> ['<json params>']\n");
+    console.error("Run `oalo call --list` to see the events you can call.");
+    process.exitCode = 2;
+    return;
+  }
+
+  let params = {};
+  const raw = rest[2];
+  if (raw) {
+    try {
+      params = JSON.parse(raw);
+    } catch (e) {
+      console.error(`params must be valid JSON: ${e.message}`);
+      process.exitCode = 2;
+      return;
+    }
+    if (params === null || typeof params !== "object" || Array.isArray(params)) {
+      console.error("params must be a JSON object");
+      process.exitCode = 2;
+      return;
+    }
+  }
+
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+
+  if (!url || !token) {
+    console.error(
+      `oalo call needs a CLI token.\n\n${HOW_TO_CONNECT}`,
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const ch = new OaloChannel({ url, token });
+  try {
+    await ch.connect();
+    const reply = await ch.call(event, params);
+    console.log(JSON.stringify(reply, null, flags.compact ? 0 : 2));
+  } catch (e) {
+    // The server often names the event itself ("loops:get failed: ..."); don't say it twice.
+    console.error(e.message.startsWith(`${event} `) ? e.message : `${event} failed: ${e.message}`);
+    if (e.code === "unknown_event") {
+      console.error(dim("Find the right name with: oalo call --list <text>. If you're sure of it, the workspace may be older than your CLI (oalo whoami shows its version)."));
+    }
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}

package/src/commands/channels.js

@@ -0,0 +1,110 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo channels`: every channel the workspace has and which bot answers it.
+ *
+ *   oalo channels                                         list them
+ *   oalo channels set whatsapp "+54 9 11 5555-0100" --bot bot_x   which bot answers the number
+ *   oalo channels set instagram @account --bot bot_x
+ *   oalo channels check whatsapp <number>                 can Oalo send on it, and why not
+ *   oalo channels connect whatsapp --bot bot_x            a link to connect a number in the browser
+ *   oalo channels connect instagram
+ *   oalo channels disconnect whatsapp|instagram <id> --yes
+ *
+ * WhatsApp and Instagram are kept by the platform, where Meta's messages
+ * arrive; the Base forwards these to it. Email is the sending address (no
+ * bot answers it), and the web chat is each published bot's own widget.
+ */
+export async function channels(flags, rest, opts = {}) {
+  const sub = rest[1] || "list";
+  const channel = rest[2];
+  const ref = rest[3];
+  if (!["list", "set", "check", "connect", "disconnect"].includes(sub)) return fail(`unknown channels command: ${sub}\n\n${USAGE}`, 2);
+  if (sub !== "list" && !["whatsapp", "instagram"].includes(channel)) return fail(`which channel? whatsapp or instagram\n\n${USAGE}`, 2);
+  if (sub === "check" && channel !== "whatsapp") return fail("check is for a WhatsApp number", 2);
+  if (["set", "check", "disconnect"].includes(sub) && !ref) return fail(`which ${channel === "whatsapp" ? "number" : "account"}? \`oalo channels\` lists them\n\n${USAGE}`, 2);
+  if (flags.bot === true) return fail("--bot needs a bot's public id (oalo bots lists them)", 2);
+  if (sub === "set" && !flags.bot) return fail("which bot? --bot <public id> (oalo bots lists them)", 2);
+  if (sub === "connect" && channel === "whatsapp" && !flags.bot) return fail("which bot answers the new number? --bot <public id>", 2);
+  if (sub === "disconnect" && !flags.yes) {
+    return fail(`disconnecting ${ref} stops the bot answering on it at once; its conversations stay. Run it again with --yes to go ahead.`, 2);
+  }
+
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo channels needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  let r;
+  try {
+    await ch.connect();
+    const params = { list: {}, set: { channel, id: ref, bot: flags.bot }, check: { id: ref }, connect: { channel, bot: flags.bot }, disconnect: { channel, id: ref } }[sub];
+    r = await ch.call(`channels:${sub === "set" ? "set_bot" : sub}`, params, sub === "check" ? 30000 : 20000);
+  } catch (e) {
+    return fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  print(sub, channel, ref, r);
+}
+
+const USAGE = [
+  "usage: oalo channels",
+  '       oalo channels set whatsapp|instagram <number or @account> --bot <bot>',
+  "       oalo channels check whatsapp <number>",
+  "       oalo channels connect whatsapp --bot <bot> | connect instagram",
+  "       oalo channels disconnect whatsapp|instagram <number or @account> --yes",
+].join("\n");
+
+const botText = (b) => (b ? `${b.name}${b.bot ? ` (${b.bot})` : ""}` : "no bot");
+
+function print(sub, channel, ref, r) {
+  if (sub === "list") {
+    const section = (title, s, line) => {
+      console.log(title);
+      if (s?.error) console.log(dim(`  ${s.error}`));
+      else if (!s?.items?.length) console.log(dim("  none connected"));
+      else for (const i of s.items) console.log(`  ${line(i)}`);
+    };
+    section("WhatsApp", r.whatsapp, (i) => `${i.number}  ${dim(`${i.name || ""}, answered by ${botText(i.bot)}${i.sending && i.sending !== "ok" ? `, sending: ${i.sending}` : ""}`)}`);
+    section("Instagram", r.instagram, (i) => `@${i.username}  ${dim(`answered by ${botText(i.bot)}`)}`);
+    console.log("Email");
+    console.log(
+      r.email
+        ? `  ${r.email.from}  ${dim(`${r.email.domain || ""}, ${r.email.verified === "verified" ? "verified" : `domain ${r.email.verified || "not verified"}`}${r.email.paused ? ", paused" : ""}; sends, no bot answers it`)}`
+        : dim("  no sending address yet"),
+    );
+    console.log("Web chat");
+    if (!r.web?.length) console.log(dim("  no published bot"));
+    for (const w of r.web || []) console.log(`  ${w.name}  ${dim(`${w.bot}'s own widget`)}`);
+    return;
+  }
+  if (sub === "set") return void console.log(`${channel === "whatsapp" ? r.number : `@${r.username}`} is answered by ${botText(r.bot)} now.`);
+  if (sub === "disconnect") return void console.log(`${channel === "whatsapp" ? r.number : `@${r.username}`} disconnected. Its conversations stay in the Inbox.`);
+  if (sub === "connect") {
+    console.log(`Open this in a browser to connect ${channel === "whatsapp" ? "a WhatsApp number" : "an Instagram account"} (Meta's sign-in runs there):`);
+    console.log(r.url);
+    if (channel === "whatsapp") console.log(dim(`The link works for a few minutes and only for you. After, oalo channels shows the number.`));
+    else console.log(dim(`After, choose its bot: oalo channels set instagram @<account> --bot <bot>.`));
+    return;
+  }
+  if (sub === "check") {
+    const status = r.channel?.send_status;
+    console.log(`${r.number}: ${status === "ok" ? "Oalo can send on it." : `Oalo can't send on it yet (${status || "unknown"}).`}`);
+    const d = r.diagnosis || {};
+    if (d.error) console.log(dim(`  ${d.error}`));
+    for (const f of d.findings || []) {
+      if (f.level === "ok") continue;
+      console.log(`  ${f.level === "blocker" ? "!" : "-"} ${f.text}${f.side === "meta" ? dim(" (on Meta's side)") : ""}`);
+    }
+    if (status && status !== "ok") process.exitCode = 1;
+  }
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}