@erdoai/cli 0.4.0

package/README.md

@@ -0,0 +1,99 @@
+# @erdoai/cli
+
+Erdo CLI — drive evals (and more) from the terminal or CI, over the same `/v1`
+REST API the MCP tools use.
+
+## Install
+
+```bash
+npm install -g @erdoai/cli   # global; then run `erdo`
+npx @erdoai/cli --help       # or run without installing
+erdo update                  # self-update to the latest published version
+```
+
+Requires Node.js 18+. User-facing install docs: https://docs.erdo.ai/cli
+
+## Auth
+
+Multi-account, like `gh`. Log in with an API key (created in Erdo); it's stored
+per account at `~/.config/erdo/config.json` and tied to your active org.
+
+```bash
+erdo login                      # browser sign-in (mints + stores a token)
+erdo login --key erdo_api_...   # headless/CI: paste an API key instead
+erdo whoami                     # active account + org
+erdo auth status                # all accounts (* = active)
+erdo auth switch [email]        # switch active account (auto-toggles with two)
+erdo logout [email]
+
+erdo org list                   # your orgs (* = active)
+erdo org use [id|slug]          # set the active org for this account
+erdo --org acme eval suites     # one-off override for a single command
+```
+
+Env overrides for CI/scripting: `ERDO_API_KEY`, `ERDO_ORG`, `ERDO_API_URL`,
+`ERDO_ACCOUNT`.
+
+## Agents & pages
+
+```bash
+erdo agent ask "what was revenue last week?" --datasets sales
+erdo agent thread --name "landing build"          # -> thread id
+erdo agent send <thread> "Build a landing page for ACME ..." --agent erdo.artifact-builder
+
+erdo pages deploy --title "ACME" --html @page.html --js @page.js --public
+erdo pages list --type html_page
+erdo pages get <artifact-id>
+```
+
+`--html/--js/--css` accept `@path` to read a file. Sending a message to a thread
+runs an agent — that's also how the artifact-builder produces a page from a brief.
+
+```bash
+erdo runs list --agent erdo.artifact-builder --status failed   # inspect agent runs
+erdo runs get <run-id>
+```
+
+## Evals
+
+```bash
+erdo eval suites                          # list suites (slug, agent, artifact?)
+erdo eval suite landing-variations        # show a suite + its cases
+erdo eval run landing-variations --watch  # run it and poll until done
+erdo eval results <run-id>                # per-case scores + lenses
+erdo eval runs --suite landing-variations # recent runs
+
+# maintain the corpus
+erdo eval case add landing-variations \
+  --name "voice-concierge" \
+  --input "Build a landing page for ACME with a voice concierge (agent id abc123) ..." \
+  --rubric '[{"criterion":"voice widget loads and is on-brand","weight":2},{"criterion":"hero + form render correctly","weight":1}]'
+erdo eval case rm landing-variations voice-concierge
+```
+
+`--watch` exits non-zero if the run doesn't complete cleanly, so it doubles as a
+CI gate.
+
+## Develop
+
+```bash
+npm install            # or yarn
+npm run dev eval suites   # run from source (tsx)
+npm run build:check       # typecheck
+npm run build             # bundle to dist/ (bin: erdo)
+```
+
+## Release
+
+Publishing is automated by `.github/workflows/publish-cli.yml`: pushing a
+`cli-v*` tag builds, typechecks, stamps the version from the tag, and runs
+`npm publish` to the npm registry (auth via the repo's `NPM_TOKEN` secret).
+
+```bash
+# bump cli/package.json "version", commit, then tag + push:
+git tag cli-v0.4.1
+git push origin cli-v0.4.1
+```
+
+The tag's version (`cli-v0.4.1` → `0.4.1`) is the published version; keep
+`cli/package.json` in sync so `erdo --version` matches locally.

package/dist/index.js

@@ -0,0 +1,1082 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { select } from "@inquirer/prompts";
+import { Command } from "commander";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var DEFAULT_API_URL = "https://api.erdo.ai";
+var CONFIG_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "erdo");
+var CONFIG_PATH = join(CONFIG_DIR, "config.json");
+var LEGACY_KEY = "default";
+function loadConfigFile() {
+  if (!existsSync(CONFIG_PATH)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    if (raw && raw.version === 2 && raw.accounts) return raw;
+    if (raw && typeof raw.token === "string") {
+      return { version: 2, activeAccount: LEGACY_KEY, accounts: { [LEGACY_KEY]: raw } };
+    }
+  } catch {
+  }
+  return null;
+}
+function saveConfigFile(file) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(file, null, 2)}
+`, { mode: 384 });
+}
+function resolveAccountKey(file, query) {
+  const keys = Object.keys(file.accounts);
+  const q = query.toLowerCase();
+  const exact = keys.find(
+    (k) => k.toLowerCase() === q || file.accounts[k].email?.toLowerCase() === q
+  );
+  if (exact) return exact;
+  const prefixed = keys.filter((k) => k.toLowerCase().startsWith(q));
+  return prefixed.length === 1 ? prefixed[0] : void 0;
+}
+function activeAccountKey(file) {
+  if (process.env.ERDO_ACCOUNT) {
+    const k = resolveAccountKey(file, process.env.ERDO_ACCOUNT);
+    if (k) return k;
+  }
+  if (file.activeAccount && file.accounts[file.activeAccount]) return file.activeAccount;
+  const keys = Object.keys(file.accounts);
+  return keys.length ? keys[0] : void 0;
+}
+function activeAccount() {
+  const file = loadConfigFile();
+  if (!file) return null;
+  const k = activeAccountKey(file);
+  return k ? { ...file.accounts[k] } : null;
+}
+function listAccounts() {
+  const file = loadConfigFile();
+  if (!file) return [];
+  const active = activeAccountKey(file);
+  return Object.entries(file.accounts).map(([key, account]) => ({ key, account, active: key === active }));
+}
+function saveAccount(key, account, activate = true) {
+  const file = loadConfigFile() ?? { version: 2, accounts: {} };
+  file.accounts[key] = { ...file.accounts[key], ...account };
+  if (activate || !file.activeAccount) file.activeAccount = key;
+  saveConfigFile(file);
+}
+function updateActiveAccount(patch) {
+  const file = loadConfigFile();
+  if (!file) return;
+  const k = activeAccountKey(file);
+  if (!k) return;
+  file.accounts[k] = { ...file.accounts[k], ...patch };
+  saveConfigFile(file);
+}
+function setActiveAccount(key) {
+  const file = loadConfigFile();
+  if (!file || !file.accounts[key]) return;
+  file.activeAccount = key;
+  saveConfigFile(file);
+}
+function removeAccount(key) {
+  const file = loadConfigFile();
+  if (!file) return;
+  delete file.accounts[key];
+  if (file.activeAccount === key) file.activeAccount = Object.keys(file.accounts)[0];
+  saveConfigFile(file);
+}
+function resolveApiUrl() {
+  return (process.env.ERDO_API_URL || DEFAULT_API_URL).replace(/\/$/, "");
+}
+function resolveToken(account) {
+  return process.env.ERDO_API_KEY || account?.token;
+}
+function resolveOrgId(account, override) {
+  return override || process.env.ERDO_ORG || account?.organizationId;
+}
+
+// src/client.ts
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "error"]);
+var POLL_STOP_STATUSES = /* @__PURE__ */ new Set([...TERMINAL_RUN_STATUSES, "awaiting_approval"]);
+var ErdoApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ErdoApiError";
+  }
+  status;
+};
+async function rawRequest(baseURL, token, orgId, method, path, body) {
+  const headers = { Authorization: `Bearer ${token}` };
+  if (orgId) headers["X-Organization-ID"] = orgId;
+  if (body !== void 0) headers["Content-Type"] = "application/json";
+  const res = await fetch(`${baseURL}${path}`, {
+    method,
+    headers,
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    let message = text;
+    try {
+      const parsed = JSON.parse(text);
+      message = parsed.message || parsed.error || text;
+    } catch {
+    }
+    throw new ErdoApiError(res.status, message || `${method} ${path} failed (${res.status})`);
+  }
+  return text ? JSON.parse(text) : void 0;
+}
+function fetchMe(token, orgId) {
+  return rawRequest(resolveApiUrl(), token, orgId, "GET", "/v1/me");
+}
+var ErdoClient = class {
+  baseURL;
+  token;
+  orgId;
+  constructor(orgOverride) {
+    this.baseURL = resolveApiUrl();
+    const acct = activeAccount();
+    const token = resolveToken(acct);
+    if (!token) {
+      throw new Error("Not logged in. Run: erdo auth login");
+    }
+    this.token = token;
+    this.orgId = resolveOrgId(acct, orgOverride);
+  }
+  request(method, path, body) {
+    return rawRequest(this.baseURL, this.token, this.orgId, method, path, body);
+  }
+  me() {
+    return this.request("GET", "/v1/me");
+  }
+  listOrganizations() {
+    return this.request("GET", "/v1/organizations");
+  }
+  listEvalSuites() {
+    return this.request("GET", "/v1/evals/suites");
+  }
+  getEvalSuite(slug) {
+    return this.request(
+      "GET",
+      `/v1/evals/suites/${encodeURIComponent(slug)}`
+    );
+  }
+  createEvalSuite(input) {
+    return this.request("POST", "/v1/evals/suites", input);
+  }
+  updateEvalSuite(slug, input) {
+    return this.request(
+      "PUT",
+      `/v1/evals/suites/${encodeURIComponent(slug)}`,
+      input
+    );
+  }
+  addEvalCase(slug, input) {
+    return this.request(
+      "POST",
+      `/v1/evals/suites/${encodeURIComponent(slug)}/cases`,
+      input
+    );
+  }
+  updateEvalCase(slug, caseName, input) {
+    return this.request(
+      "PUT",
+      `/v1/evals/suites/${encodeURIComponent(slug)}/cases/${encodeURIComponent(caseName)}`,
+      input
+    );
+  }
+  removeEvalCase(slug, caseName) {
+    return this.request(
+      "DELETE",
+      `/v1/evals/suites/${encodeURIComponent(slug)}/cases/${encodeURIComponent(caseName)}`
+    );
+  }
+  runEvalSuite(slug, concurrency) {
+    return this.request(
+      "POST",
+      `/v1/evals/suites/${encodeURIComponent(slug)}/run`,
+      { concurrency: concurrency ?? 0 }
+    );
+  }
+  getEvalRun(runID) {
+    return this.request(
+      "GET",
+      `/v1/evals/runs/${encodeURIComponent(runID)}`
+    );
+  }
+  // --- agents ---
+  ask(input) {
+    return this.request("POST", "/v1/ask", input);
+  }
+  createThread(input) {
+    return this.request(
+      "POST",
+      "/v1/threads-create",
+      input
+    );
+  }
+  sendMessage(threadID, input) {
+    return this.request(
+      "POST",
+      `/v1/threads/${encodeURIComponent(threadID)}/send`,
+      { thread_id: threadID, ...input }
+    );
+  }
+  // waitForThreadRun polls the latest run on a thread until it reaches a terminal
+  // status — used after an async ask/send so the caller can return the answer
+  // without holding a long HTTP request open. Returns the final run (output/error
+  // populated). Returns null if the deadline passes WITHOUT the run reaching a
+  // terminal status — including the case where it's still running — so callers
+  // surface a timeout rather than printing a partial/empty result as success.
+  //
+  // ignoreRunID is the id of the run that was already latest on the thread BEFORE
+  // we kicked off the new one. The async invocation creates its run row a moment
+  // after the HTTP call returns, so without this the first poll on a reused thread
+  // would return that prior (already-terminal) run and print a stale answer. We
+  // skip it and wait for a genuinely new run to appear.
+  async waitForThreadRun(threadID, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 3e3;
+    const deadline = Date.now() + (opts.timeoutMs ?? 15 * 60 * 1e3);
+    while (Date.now() < deadline) {
+      const { runs } = await this.listAgentRuns({ thread: threadID, limit: 1 });
+      const run = runs[0];
+      if (run && run.id !== opts.ignoreRunID) {
+        opts.onTick?.(run.status);
+        if (POLL_STOP_STATUSES.has(run.status)) return run;
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return null;
+  }
+  // latestRunID returns the id of the most recent run on a thread (or undefined),
+  // used to baseline an async wait so it doesn't return a pre-existing run.
+  async latestRunID(threadID) {
+    const { runs } = await this.listAgentRuns({ thread: threadID, limit: 1 });
+    return runs[0]?.id;
+  }
+  listThreads() {
+    return this.request("GET", "/v1/threads");
+  }
+  // --- datasets ---
+  listDatasets() {
+    return this.request(
+      "GET",
+      "/v1/datasets"
+    );
+  }
+  queryDataset(slug, query, timezone) {
+    return this.request("POST", `/v1/datasets/${encodeURIComponent(slug)}/query-nl`, {
+      query,
+      timezone
+    });
+  }
+  // --- knowledge ---
+  listKnowledge() {
+    return this.request("GET", "/v1/knowledge");
+  }
+  searchKnowledge(query, limit) {
+    const params = new URLSearchParams({ query });
+    if (limit) params.set("limit", String(limit));
+    return this.request("GET", `/v1/knowledge-search?${params.toString()}`);
+  }
+  // --- automations (heartbeats) ---
+  listHeartbeats() {
+    return this.request(
+      "GET",
+      "/v1/heartbeats"
+    );
+  }
+  runHeartbeat(id) {
+    return this.request("POST", `/v1/heartbeats/${encodeURIComponent(id)}/run`, {});
+  }
+  // --- collections ---
+  listCollections() {
+    return this.request("GET", "/v1/collections");
+  }
+  createCollection(slug) {
+    return this.request("POST", "/v1/collections", { slug });
+  }
+  getCollectionItem(slug, key) {
+    return this.request(
+      "GET",
+      `/v1/collections/${encodeURIComponent(slug)}/items/${encodeURIComponent(key)}`
+    );
+  }
+  setCollectionItem(slug, key, value) {
+    return this.request(
+      "PUT",
+      `/v1/collections/${encodeURIComponent(slug)}/items/${encodeURIComponent(key)}`,
+      { value }
+    );
+  }
+  // --- agent runs ---
+  listAgentRuns(opts) {
+    const params = new URLSearchParams();
+    if (opts.agent) params.set("agent_key", opts.agent);
+    if (opts.thread) params.set("thread_id", opts.thread);
+    if (opts.limit) params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    return this.request("GET", `/v1/runs${qs ? `?${qs}` : ""}`);
+  }
+  getAgentRun(id) {
+    return this.request("GET", `/v1/runs/${encodeURIComponent(id)}`);
+  }
+  // --- pages / artifacts ---
+  deployPage(input) {
+    return this.request("POST", "/v1/pages", input);
+  }
+  updatePage(pageID, input) {
+    return this.request("PUT", `/v1/pages/${encodeURIComponent(pageID)}`, input);
+  }
+  validatePage(input) {
+    return this.request("POST", "/v1/pages/validate", input);
+  }
+  listArtifacts(type, limit) {
+    const params = new URLSearchParams();
+    if (type) params.set("type", type);
+    if (limit) params.set("limit", String(limit));
+    const qs = params.toString();
+    return this.request("GET", `/v1/artifacts${qs ? `?${qs}` : ""}`);
+  }
+  getArtifact(id) {
+    return this.request("GET", `/v1/artifacts/${encodeURIComponent(id)}`);
+  }
+  listEvalRuns(suiteSlug, limit) {
+    const params = new URLSearchParams();
+    if (suiteSlug) params.set("suite_slug", suiteSlug);
+    if (limit) params.set("limit", String(limit));
+    const qs = params.toString();
+    return this.request("GET", `/v1/evals/runs${qs ? `?${qs}` : ""}`);
+  }
+};
+
+// src/login.ts
+import { spawn } from "child_process";
+import { randomBytes } from "crypto";
+import { createServer } from "http";
+import { hostname } from "os";
+var REDIRECT_URI = "http://localhost:8080/callback";
+var PORT = 8080;
+var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+function waitForCode(state) {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const u = new URL(req.url || "", REDIRECT_URI);
+      if (u.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const code = u.searchParams.get("code");
+      const gotState = u.searchParams.get("state");
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(
+        '<html><head><meta charset="utf-8"></head><body><h2>Erdo CLI \u2014 authenticated. You can close this tab.</h2></body></html>'
+      );
+      server.close();
+      if (gotState !== state) return reject(new Error("state mismatch \u2014 login aborted"));
+      if (!code) return reject(new Error("no authorization code returned"));
+      resolve(code);
+    });
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        reject(new Error(`port ${PORT} is in use \u2014 free it and retry (or use 'erdo login --key')`));
+      } else {
+        reject(err);
+      }
+    });
+    server.listen(PORT, () => {
+      const api = resolveApiUrl();
+      const tokenName = (hostname() || "erdo-cli").slice(0, 64);
+      const authURL = `${api}/auth/cli?response_type=code&client_id=erdo-cli&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${state}&token_name=${encodeURIComponent(tokenName)}`;
+      console.log(`Opening your browser to authorize\u2026
+If it doesn't open, visit:
+  ${authURL}`);
+      openBrowser(authURL);
+    });
+    setTimeout(() => {
+      server.close();
+      reject(new Error("login timed out after 3 minutes"));
+    }, LOGIN_TIMEOUT_MS).unref();
+  });
+}
+async function browserLogin() {
+  const state = randomBytes(16).toString("hex");
+  const code = await waitForCode(state);
+  const res = await fetch(`${resolveApiUrl()}/auth/cli/callback`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: "erdo-cli",
+      code,
+      redirect_uri: REDIRECT_URI
+    })
+  });
+  if (!res.ok) {
+    throw new Error(`token exchange failed (${res.status}): ${await res.text()}`);
+  }
+  const data = await res.json();
+  if (!data.access_token) throw new Error("token exchange returned no access_token");
+  const me = await fetchMe(data.access_token);
+  return { token: data.access_token, me };
+}
+
+// src/update.ts
+import { spawnSync } from "child_process";
+var PKG = "@erdoai/cli";
+var MANUAL_HINT = `npm install -g ${PKG}@latest`;
+function isNewer(latest, current) {
+  const a = latest.split(".").map(Number);
+  const b = current.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) > (b[i] ?? 0)) return true;
+    if ((a[i] ?? 0) < (b[i] ?? 0)) return false;
+  }
+  return false;
+}
+async function update(current) {
+  let latest;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`);
+    if (res.ok) latest = (await res.json()).version;
+  } catch {
+  }
+  if (!latest) {
+    console.error(`Could not reach the npm registry. Try manually: ${MANUAL_HINT}`);
+    process.exit(1);
+  }
+  if (!isNewer(latest, current)) {
+    console.log(`Already up to date (v${current}).`);
+    return;
+  }
+  console.log(`Updating ${PKG} v${current} \u2192 v${latest}\u2026`);
+  const result = spawnSync("npm", ["install", "-g", `${PKG}@latest`], {
+    stdio: "inherit",
+    // npm is npm.cmd on Windows; needs a shell to resolve.
+    shell: process.platform === "win32"
+  });
+  if (result.status !== 0) {
+    console.error(`Update failed. Try manually: ${MANUAL_HINT}`);
+    process.exit(result.status ?? 1);
+  }
+  console.log(`Updated to v${latest}.`);
+}
+
+// src/index.ts
+var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+function fail(err) {
+  if (err instanceof ErdoApiError) {
+    console.error(`Error ${err.status}: ${err.message}`);
+  } else if (err instanceof Error) {
+    console.error(`Error: ${err.message}`);
+  } else {
+    console.error("Error:", err);
+  }
+  process.exit(1);
+}
+function print(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function summariseResults(results, cases = []) {
+  const nameByID = new Map(cases.map((c) => [c.id, c.name]));
+  for (const r of results) {
+    const status = r.agent_error ? "ERROR" : r.passed ? "PASS" : "FAIL";
+    const name = nameByID.get(r.case_id) ?? r.case_id;
+    console.log(`  [${status}] ${r.score.toFixed(2)}  ${name}`);
+    if (r.agent_error) console.log(`      agent error: ${r.agent_error}`);
+    for (const c of r.judge_criteria_scores || []) {
+      console.log(`      - ${c.score}  ${c.criterion}`);
+    }
+  }
+}
+var program = new Command();
+program.name("erdo").description("Erdo CLI").version(pkg.version).option("--org <idOrSlug>", "org to target for this command (overrides the active org)");
+program.hook("preAction", (thisCommand) => {
+  const org2 = thisCommand.opts().org;
+  if (org2) process.env.ERDO_ORG = org2;
+});
+async function doLogin(opts) {
+  let token;
+  let me;
+  if (opts.key) {
+    token = opts.key.trim();
+    me = await fetchMe(token);
+  } else {
+    ({ token, me } = await browserLogin());
+  }
+  saveAccount(me.email || me.user_id, {
+    token,
+    email: me.email,
+    organizationId: me.organization_id,
+    organizationName: me.organization_name
+  });
+  console.log(
+    `Logged in as ${me.email || me.user_id}${me.organization_name ? ` (org: ${me.organization_name})` : ""}.`
+  );
+}
+var auth = program.command("auth").description("Manage authentication");
+auth.command("login").description("Log in via browser (or --key for CI); stored per account").option("--key <apiKey>", "API key for headless/CI (skips the browser flow)").action(async (opts) => {
+  try {
+    await doLogin(opts);
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("login").description("Log in via browser (alias for auth login)").option("--key <apiKey>", "API key").action(async (opts) => {
+  try {
+    await doLogin(opts);
+  } catch (e) {
+    fail(e);
+  }
+});
+auth.command("status").description("List logged-in accounts (* = active)").action(() => {
+  const accounts = listAccounts();
+  if (accounts.length === 0) {
+    console.log("Not logged in. Run: erdo auth login");
+    return;
+  }
+  for (const { key, account, active } of accounts) {
+    console.log(`${active ? "*" : " "} ${key}`);
+    console.log(`    token: ${account.token.slice(0, 10)}\u2026`);
+    console.log(`    org:   ${account.organizationName ?? account.organizationId ?? "(none)"}`);
+  }
+  console.log("Switch with: erdo auth switch");
+});
+auth.command("switch [account]").description("Switch the active account").action(async (accountQuery) => {
+  try {
+    const file = loadConfigFile();
+    const accounts = listAccounts();
+    if (!file || accounts.length === 0) throw new Error("Not logged in. Run: erdo auth login");
+    let key;
+    if (accountQuery) {
+      key = resolveAccountKey(file, accountQuery);
+      if (!key) throw new Error(`No account matching "${accountQuery}"`);
+    } else if (accounts.length === 2) {
+      key = accounts.find((a) => !a.active)?.key;
+    } else if (accounts.length === 1) {
+      console.log("Only one account.");
+      return;
+    } else {
+      key = await select({
+        message: "Switch to account:",
+        choices: accounts.map((a) => ({
+          name: `${a.key}${a.active ? " (current)" : ""}`,
+          value: a.key
+        }))
+      });
+    }
+    if (key) {
+      setActiveAccount(key);
+      console.log(`Switched to ${key}.`);
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("logout [account]").description("Log out an account (default: the active one)").action((accountQuery) => {
+  const file = loadConfigFile();
+  if (!file) {
+    console.log("Not logged in.");
+    return;
+  }
+  const key = accountQuery ? resolveAccountKey(file, accountQuery) : listAccounts().find((a) => a.active)?.key ?? void 0;
+  if (!key) {
+    console.log("No matching account.");
+    return;
+  }
+  removeAccount(key);
+  console.log(`Logged out ${key}.`);
+});
+program.command("whoami").description("Show the active account and org").action(async () => {
+  try {
+    const me = await new ErdoClient().me();
+    console.log(`${me.email || me.user_id} \u2014 org: ${me.organization_name || me.organization_id}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("update").description("Update the CLI to the latest published version").action(async () => {
+  try {
+    await update(pkg.version);
+  } catch (e) {
+    fail(e);
+  }
+});
+var org = program.command("org").description("Manage the active organization");
+org.command("list").description("List your organizations (* = active)").action(async () => {
+  try {
+    const api = new ErdoClient();
+    const [{ organizations }, me] = await Promise.all([api.listOrganizations(), api.me()]);
+    for (const o of organizations) {
+      console.log(`${o.id === me.organization_id ? "*" : " "} ${o.slug || "-"}	${o.name}	${o.id}`);
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+org.command("use [idOrSlug]").description("Set the active org for the current account").action(async (idOrSlug) => {
+  try {
+    const { organizations } = await new ErdoClient().listOrganizations();
+    let chosen = idOrSlug ? organizations.find(
+      (o) => o.id === idOrSlug || o.slug.toLowerCase() === idOrSlug.toLowerCase()
+    ) : void 0;
+    if (!chosen && !idOrSlug) {
+      const id = await select({
+        message: "Use organization:",
+        choices: organizations.map((o) => ({ name: `${o.name} (${o.slug || o.id})`, value: o.id }))
+      });
+      chosen = organizations.find((o) => o.id === id);
+    }
+    if (!chosen) throw new Error(`No org matching "${idOrSlug}"`);
+    updateActiveAccount({ organizationId: chosen.id, organizationName: chosen.name });
+    console.log(`Active org: ${chosen.name}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+var evalCmd = program.command("eval").description("Run and manage evals");
+evalCmd.command("suites").description("List eval suites in the active org (+ global)").action(async () => {
+  try {
+    const { suites } = await new ErdoClient().listEvalSuites();
+    for (const s of suites) {
+      console.log(`${s.slug}	${s.agent_key}	artifact=${s.evaluate_artifact}	${s.name}`);
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+evalCmd.command("suite <slug>").description("Show a suite and its cases").action(async (slug) => {
+  try {
+    print(await new ErdoClient().getEvalSuite(slug));
+  } catch (e) {
+    fail(e);
+  }
+});
+function parseRubric(json) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    throw new Error(`--rubric must be valid JSON, e.g. '[{"criterion":"brand","weight":1}]'`);
+  }
+}
+var collect = (v, acc) => {
+  acc.push(v);
+  return acc;
+};
+function caseScoringPayload(opts) {
+  const out = {};
+  if (opts.rubric) out.rubric = parseRubric(opts.rubric);
+  if (opts.evaluator.length > 0) {
+    out.evaluators = opts.evaluator.map((e, i) => {
+      try {
+        return JSON.parse(e);
+      } catch {
+        throw new Error(`--evaluator #${i + 1} must be valid JSON ({type,weight,...})`);
+      }
+    });
+  }
+  if (!out.rubric && !out.evaluators) {
+    throw new Error("provide --rubric and/or --evaluator");
+  }
+  return out;
+}
+evalCmd.command("update <slug>").description("Update a suite's settings (only the flags you pass change)").option("--name <name>", "new name").option("--description <text>", "new description").option("--agent <key>", "repoint the agent under test, e.g. erdo.data-question-answerer").option("--judge <model>", "new judge model").option("--threshold <n>", "new pass threshold 0-5", (v) => parseFloat(v)).option("--evaluate-artifact <bool>", "judge the rendered page (true/false)").option("--cron <bool>", "include in the daily cron (true/false)").action(
+  async (slug, opts) => {
+    try {
+      const parseBool = (v) => v === void 0 ? void 0 : v === "true" || v === "1" || v === "yes";
+      const res = await new ErdoClient().updateEvalSuite(slug, {
+        name: opts.name,
+        description: opts.description,
+        agent_key: opts.agent,
+        judge_model: opts.judge,
+        pass_threshold: opts.threshold,
+        evaluate_artifact: parseBool(opts.evaluateArtifact),
+        cron_enabled: parseBool(opts.cron)
+      });
+      print(res);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+evalCmd.command("create <name>").description("Create a suite (in the active org)").requiredOption("--agent <key>", "agent under test, e.g. erdo.artifact-builder").option("--description <text>", "description").option("--judge <model>", "judge model").option("--threshold <n>", "pass threshold 0-5", (v) => parseFloat(v)).option("--evaluate-artifact", "judge the rendered page (visual suite)").option("--no-cron", "exclude from the daily cron (recommended for artifact suites)").requiredOption("--case <json>", "first case: {name,input,rubric,tags?}", (v, acc) => {
+  acc.push(v);
+  return acc;
+}, []).action(
+  async (name, opts) => {
+    try {
+      const cases = opts.case.map((c) => JSON.parse(c));
+      const res = await new ErdoClient().createEvalSuite({
+        name,
+        description: opts.description,
+        agent_key: opts.agent,
+        judge_model: opts.judge,
+        pass_threshold: opts.threshold,
+        evaluate_artifact: !!opts.evaluateArtifact,
+        cron_enabled: opts.cron,
+        // commander sets false when --no-cron
+        cases
+      });
+      print(res);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+evalCmd.command("run <slug>").description("Run a suite; --watch polls until it completes").option("-w, --watch", "poll until the run finishes and print results").option("-c, --concurrency <n>", "parallel cases", (v) => parseInt(v, 10)).action(async (slug, opts) => {
+  try {
+    const api = new ErdoClient();
+    const { run_id } = await api.runEvalSuite(slug, opts.concurrency);
+    console.log(`run_id: ${run_id}`);
+    if (!opts.watch) return;
+    for (; ; ) {
+      await sleep(5e3);
+      const { run, results, cases } = await api.getEvalRun(run_id);
+      if (run.status === "running") {
+        console.log(`  ...running (${results.length}/${run.total_cases} cases scored)`);
+        continue;
+      }
+      console.log(
+        `
+${run.status}: ${run.passed_cases}/${run.total_cases} passed, avg ${run.avg_score.toFixed(2)}`
+      );
+      summariseResults(results, cases);
+      if (run.status !== "completed" || run.passed_cases < run.total_cases) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+evalCmd.command("results <runId>").description("Show a run's results").option("--json", "print the full JSON").action(async (runId, opts) => {
+  try {
+    const data = await new ErdoClient().getEvalRun(runId);
+    if (opts.json) {
+      print(data);
+      return;
+    }
+    const { run, results, cases } = data;
+    console.log(
+      `${run.status}: ${run.passed_cases}/${run.total_cases} passed, avg ${run.avg_score.toFixed(2)}`
+    );
+    summariseResults(results, cases);
+  } catch (e) {
+    fail(e);
+  }
+});
+evalCmd.command("runs").description("List recent runs").option("-s, --suite <slug>", "filter to one suite").option("-l, --limit <n>", "max runs", (v) => parseInt(v, 10)).action(async (opts) => {
+  try {
+    const { runs } = await new ErdoClient().listEvalRuns(opts.suite, opts.limit);
+    for (const r of runs) {
+      console.log(
+        `${r.id}	${r.status}	${r.passed_cases}/${r.total_cases}	avg ${r.avg_score.toFixed(2)}`
+      );
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+var caseCmd = evalCmd.command("case").description("Manage cases in a suite");
+caseCmd.command("add <slug>").description("Add a case to a suite").requiredOption("--name <name>", "case name").requiredOption("--input <brief>", "the brief/prompt sent to the agent (the evaluated turn)").option(
+  "--setup <msg>",
+  "a turn to run BEFORE input, same thread/agent (repeatable; e.g. 'create a voice widget for X')",
+  collect,
+  []
+).option("--rubric <json>", 'LLM rubric: JSON array of {"criterion","weight"}').option("--evaluator <json>", "evaluator JSON {type,weight,...} (repeatable)", collect, []).option("--tags <csv>", "comma-separated tags").action(
+  async (slug, opts) => {
+    try {
+      const res = await new ErdoClient().addEvalCase(slug, {
+        name: opts.name,
+        input: opts.input,
+        setup_messages: opts.setup,
+        ...caseScoringPayload(opts),
+        tags: opts.tags ? opts.tags.split(",").map((t) => t.trim()) : []
+      });
+      print(res);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+caseCmd.command("update <slug> <caseName>").description("Replace a case's brief, scoring, and tags").requiredOption("--input <brief>", "replacement brief/prompt (the evaluated turn)").option("--setup <msg>", "replacement pre-turn run before input (repeatable; omit for none)", collect, []).option("--rubric <json>", "replacement LLM rubric JSON").option("--evaluator <json>", "evaluator JSON {type,weight,...} (repeatable)", collect, []).option("--tags <csv>", "comma-separated tags").action(
+  async (slug, caseName, opts) => {
+    try {
+      const res = await new ErdoClient().updateEvalCase(slug, caseName, {
+        name: caseName,
+        input: opts.input,
+        setup_messages: opts.setup,
+        ...caseScoringPayload(opts),
+        tags: opts.tags ? opts.tags.split(",").map((t) => t.trim()) : []
+      });
+      print(res);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+caseCmd.command("rm <slug> <caseName>").description("Archive a case from a suite").action(async (slug, caseName) => {
+  try {
+    await new ErdoClient().removeEvalCase(slug, caseName);
+    console.log(`removed: ${caseName}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+var agentCmd = program.command("agent").description("Run agents");
+agentCmd.command("ask <question>").description("Ask the data-question agent (one-shot); prints the answer").option("-d, --datasets <csv>", "dataset slugs to scope to").option(
+  "--async",
+  "kick off the run and poll for the result instead of holding one long request open (use for slow builds)"
+).action(async (question, opts) => {
+  try {
+    const client = new ErdoClient();
+    const res = await client.ask({
+      question,
+      dataset_slugs: opts.datasets ? opts.datasets.split(",").map((s) => s.trim()) : void 0,
+      async: opts.async
+    });
+    if (opts.async) {
+      process.stderr.write(`thread: ${res.thread_id}
+running\u2026`);
+      const run = await client.waitForThreadRun(res.thread_id, {
+        onTick: () => process.stderr.write(".")
+      });
+      process.stderr.write("\n");
+      if (!run) throw new Error("timed out waiting for the run to finish");
+      if (run.status === "awaiting_approval")
+        throw new Error("run needs approval \u2014 approve it in the Erdo app, then re-check the thread");
+      if (run.error) throw new Error(run.error);
+      console.log(run.output || `(status: ${run.status})`);
+      console.log(`
+thread: ${res.thread_id}`);
+      return;
+    }
+    console.log(res.answer || `(status: ${res.status})`);
+    console.log(`
+thread: ${res.thread_id}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+agentCmd.command("send <threadId> <message>").description("Send a message to a thread and print the agent's reply").option("-a, --agent <key>", "agent to invoke (e.g. erdo.artifact-builder)").option(
+  "--async",
+  "kick off the run and poll for the result instead of holding one long request open (use for slow builds)"
+).action(async (threadId, message, opts) => {
+  try {
+    const client = new ErdoClient();
+    const baselineRunID = opts.async ? await client.latestRunID(threadId) : void 0;
+    const res = await client.sendMessage(threadId, {
+      message,
+      agent_key: opts.agent,
+      async: opts.async
+    });
+    if (res.error) throw new Error(res.error);
+    if (opts.async) {
+      process.stderr.write("running\u2026");
+      const run = await client.waitForThreadRun(threadId, {
+        ignoreRunID: baselineRunID,
+        onTick: () => process.stderr.write(".")
+      });
+      process.stderr.write("\n");
+      if (!run) throw new Error("timed out waiting for the run to finish");
+      if (run.status === "awaiting_approval")
+        throw new Error("run needs approval \u2014 approve it in the Erdo app, then re-check the thread");
+      if (run.error) throw new Error(run.error);
+      console.log(run.output || `(status: ${run.status})`);
+      return;
+    }
+    console.log(res.answer || `(status: ${res.status})`);
+  } catch (e) {
+    fail(e);
+  }
+});
+agentCmd.command("thread").description("Create a thread; prints its id").option("-n, --name <name>", "thread name").option("-d, --datasets <csv>", "dataset UUIDs to attach").action(async (opts) => {
+  try {
+    const res = await new ErdoClient().createThread({
+      name: opts.name,
+      dataset_ids: opts.datasets ? opts.datasets.split(",").map((s) => s.trim()) : void 0
+    });
+    console.log(res.id);
+  } catch (e) {
+    fail(e);
+  }
+});
+agentCmd.command("threads").description("List your threads").action(async () => {
+  try {
+    const { threads } = await new ErdoClient().listThreads();
+    for (const t of threads) console.log(`${t.id}	${t.name}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+var runsCmd = program.command("runs").description("Inspect agent runs");
+runsCmd.command("list").description("List agent runs (filter by agent OR thread \u2014 mutually exclusive)").option("-a, --agent <key>", "filter by agent key").option("-t, --thread <id>", "filter to a thread").option("-l, --limit <n>", "max runs", (v) => parseInt(v, 10)).action(async (opts) => {
+  try {
+    const { runs } = await new ErdoClient().listAgentRuns(opts);
+    for (const r of runs) console.log(`${r.id}	${r.status}	${r.agent_key}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+runsCmd.command("get <id>").description("Show an agent run (status, output, trace metadata)").action(async (id) => {
+  try {
+    print(await new ErdoClient().getAgentRun(id));
+  } catch (e) {
+    fail(e);
+  }
+});
+var pagesCmd = program.command("pages").description("Create and manage pages/artifacts");
+function readMaybeFile(v) {
+  if (!v) return void 0;
+  return v.startsWith("@") ? readFileSync2(v.slice(1), "utf8") : v;
+}
+pagesCmd.command("deploy").description("Deploy a page (HTML/React); --html/--js/--css accept @file").requiredOption("--title <title>", "page title").requiredOption("--html <htmlOr@file>", "HTML (or @path to a file)").option("--js <jsOr@file>", "JS/JSX (or @path)").option("--css <cssOr@file>", "CSS (or @path)").option("--runtime <runtime>", "react-tailwind (default) or none").option("--datasets <csv>", "dataset slugs the page reads").option("--writable-datasets <csv>", "dataset slugs the page may write via erdo.insertRows").option("--collections <csv>", "named collection slugs the page reads").option("--writable-collections <csv>", "named collection slugs the page may write").option("--public", "make the page publicly viewable").action(
+  async (opts) => {
+    try {
+      const csv = (v) => v ? v.split(",").map((s) => s.trim()) : void 0;
+      const res = await new ErdoClient().deployPage({
+        title: opts.title,
+        html: readMaybeFile(opts.html),
+        js: readMaybeFile(opts.js),
+        css: readMaybeFile(opts.css),
+        runtime: opts.runtime,
+        dataset_slugs: csv(opts.datasets),
+        writable_dataset_slugs: csv(opts.writableDatasets),
+        collection_slugs: csv(opts.collections),
+        writable_collection_slugs: csv(opts.writableCollections),
+        public: !!opts.public
+      });
+      console.log(`${res.id}	${res.public_url || res.url}`);
+      if (res.warning) console.error(`warning: ${res.warning}`);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+pagesCmd.command("validate").description("Validate page content without deploying").requiredOption("--html <htmlOr@file>", "HTML (or @path)").option("--js <jsOr@file>", "JS/JSX (or @path)").option("--css <cssOr@file>", "CSS (or @path)").option("--runtime <runtime>", "react-tailwind (default) or none").action(async (opts) => {
+  try {
+    print(
+      await new ErdoClient().validatePage({
+        html: readMaybeFile(opts.html),
+        js: readMaybeFile(opts.js),
+        css: readMaybeFile(opts.css),
+        runtime: opts.runtime
+      })
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+pagesCmd.command("list").description("List artifacts (pages, charts, ...)").option("-t, --type <type>", "filter by type (e.g. html_page)").option("-l, --limit <n>", "max results", (v) => parseInt(v, 10)).action(async (opts) => {
+  try {
+    const { artifacts } = await new ErdoClient().listArtifacts(opts.type, opts.limit);
+    for (const a of artifacts) console.log(`${a.id}	${a.type}	${a.title}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+pagesCmd.command("get <id>").description("Show an artifact").action(async (id) => {
+  try {
+    print(await new ErdoClient().getArtifact(id));
+  } catch (e) {
+    fail(e);
+  }
+});
+var datasetsCmd = program.command("datasets").description("Datasets");
+datasetsCmd.command("list").description("List datasets").action(async () => {
+  try {
+    const { datasets } = await new ErdoClient().listDatasets();
+    for (const d of datasets) console.log(`${d.slug}	${d.type}	${d.status}	${d.name}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+datasetsCmd.command("query <slug> <question>").description("Ask a natural-language question of a dataset").action(async (slug, question) => {
+  try {
+    print(await new ErdoClient().queryDataset(slug, question));
+  } catch (e) {
+    fail(e);
+  }
+});
+var knowledgeCmd = program.command("knowledge").description("Knowledge objects");
+knowledgeCmd.command("list").description("List knowledge objects").action(async () => {
+  try {
+    print(await new ErdoClient().listKnowledge());
+  } catch (e) {
+    fail(e);
+  }
+});
+knowledgeCmd.command("search <query>").description("Semantic search over knowledge").option("-l, --limit <n>", "max results", (v) => parseInt(v, 10)).action(async (query, opts) => {
+  try {
+    print(await new ErdoClient().searchKnowledge(query, opts.limit));
+  } catch (e) {
+    fail(e);
+  }
+});
+var autoCmd = program.command("automations").description("Scheduled automations (heartbeats)");
+autoCmd.command("list").description("List automations").action(async () => {
+  try {
+    const { heartbeats } = await new ErdoClient().listHeartbeats();
+    for (const h of heartbeats) console.log(`${h.id}	${h.state}	${h.name}`);
+  } catch (e) {
+    fail(e);
+  }
+});
+autoCmd.command("run <id>").description("Trigger an automation now").action(async (id) => {
+  try {
+    print(await new ErdoClient().runHeartbeat(id));
+  } catch (e) {
+    fail(e);
+  }
+});
+var collCmd = program.command("collections").description("Named key/value collections");
+collCmd.command("list").description("List collections").action(async () => {
+  try {
+    print(await new ErdoClient().listCollections());
+  } catch (e) {
+    fail(e);
+  }
+});
+collCmd.command("create <slug>").description("Create a named collection (slug: lowercase letters, digits, hyphens)").action(async (slug) => {
+  try {
+    print(await new ErdoClient().createCollection(slug));
+  } catch (e) {
+    fail(e);
+  }
+});
+collCmd.command("get <slug> <key>").description("Get a collection item").action(async (slug, key) => {
+  try {
+    print(await new ErdoClient().getCollectionItem(slug, key));
+  } catch (e) {
+    fail(e);
+  }
+});
+collCmd.command("set <slug> <key> <jsonValue>").description("Set a collection item (value is parsed as JSON, else stored as string)").action(async (slug, key, jsonValue) => {
+  try {
+    let value;
+    try {
+      value = JSON.parse(jsonValue);
+    } catch {
+      value = jsonValue;
+    }
+    print(await new ErdoClient().setCollectionItem(slug, key, value));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.parseAsync(process.argv).catch(fail);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@erdoai/cli",
+  "version": "0.4.0",
+  "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
+  "type": "module",
+  "bin": {
+    "erdo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "scripts/postinstall.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "keywords": [
+    "erdo",
+    "ai",
+    "agent",
+    "cli",
+    "datasets",
+    "evals"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erdoai/erdo.git",
+    "directory": "cli"
+  },
+  "homepage": "https://docs.erdo.ai/cli",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "build:check": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,42 @@
+// Friendly getting-started hint, printed once after `npm install -g @erdoai/cli`.
+// Stays quiet in CI and non-interactive installs (and never fails the install).
+import { existsSync } from "node:fs";
+
+try {
+  // In our own source checkout the package ships `dist` + this script but never
+  // `src`, so a sibling `src/` means this is a dev `npm install` — stay quiet.
+  const devCheckout = existsSync(new URL("../src", import.meta.url));
+
+  const quiet =
+    devCheckout ||
+    process.env.CI ||
+    process.env.ERDO_NO_POSTINSTALL ||
+    !process.stdout.isTTY;
+
+  if (!quiet) {
+    const c = (code, s) => `\x1b[${code}m${s}\x1b[0m`;
+    const b = (s) => c("1", s);
+    const dim = (s) => c("2", s);
+    const blue = (s) => c("34", s);
+
+    const lines = [
+      "",
+      b("  Erdo CLI installed.") +
+        " " +
+        dim("Drive agents, pages, datasets, and evals from your terminal or CI."),
+      "",
+      b("  Get started:"),
+      `    ${b("erdo login")}                  ${dim("Sign in via your browser")}`,
+      `    ${b("erdo org use")}                ${dim("Choose your organization")}`,
+      `    ${b('erdo agent ask "..."')}        ${dim("Ask your first question")}`,
+      "",
+      `  Docs        ${blue("https://docs.erdo.ai/cli")}`,
+      `  Quickstart  ${blue("https://docs.erdo.ai/quickstart")}`,
+      `  Use with AI ${blue("https://docs.erdo.ai/mcp/overview")} ${dim("(Claude, Codex, Cursor…)")}`,
+      "",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+} catch {
+  // never let a cosmetic hint break installation
+}