@aeosome/cli 0.0.0-stage → 0.1.0

package/dist/aeosome.js

@@ -0,0 +1,830 @@
+#!/usr/bin/env node
+
+// src/args.ts
+var SWITCHES = new Set(["json", "help", "version"]);
+var isFlag = (token) => token?.startsWith("--") ?? false;
+function splitFlag(token) {
+  const body = token.slice(2);
+  const eq = body.indexOf("=");
+  return eq === -1 ? [body, undefined] : [body.slice(0, eq), body.slice(eq + 1)];
+}
+function takesValue(name, next) {
+  return !SWITCHES.has(name) && next !== undefined && !isFlag(next);
+}
+function flagValue(name, inline, next) {
+  if (inline !== undefined)
+    return { value: inline, consumed: 0 };
+  if (takesValue(name, next))
+    return { value: next, consumed: 1 };
+  return { value: true, consumed: 0 };
+}
+function consume(argv, i, flags, words) {
+  const token = argv[i] ?? "";
+  if (!isFlag(token))
+    return words.push(token) && 1;
+  const [name, inline] = splitFlag(token);
+  const { value, consumed } = flagValue(name, inline, argv[i + 1]);
+  flags.set(name, value);
+  return 1 + consumed;
+}
+function parseArgs(argv) {
+  const flags = new Map;
+  const words = [];
+  let i = 0;
+  while (i < argv.length)
+    i += consume(argv, i, flags, words);
+  const [command, ...positionals] = words;
+  return { command, positionals, flags };
+}
+
+// src/client.ts
+var VERSION = "0.1.0";
+var EXIT = {
+  ok: 0,
+  usage: 1,
+  auth: 2,
+  plan: 3,
+  api: 4,
+  network: 5
+};
+
+class CliError extends Error {
+  code;
+  exitCode;
+  constructor(code, message, exitCode) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+var TIMEOUT_MS = 30000;
+async function parse(response) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+var messageOf = (status, body) => body.message ?? body.error ?? `HTTP ${status}`;
+var UPGRADE_URL = "https://app.aeosome.com/dashboard/settings/billing";
+function failureFor(status, body) {
+  const message = messageOf(status, body);
+  if (status === 401)
+    return new CliError("UNAUTHORIZED", "The API key is missing, invalid or revoked. Run `aeosome login`.", EXIT.auth);
+  if (body.code === "FEATURE_DISABLED")
+    return new CliError(body.code, `${message} Upgrade at ${UPGRADE_URL}`, EXIT.plan);
+  return new CliError(body.code ?? `HTTP_${status}`, message, EXIT.api);
+}
+async function send(url, init) {
+  try {
+    return await fetch(url, {
+      ...init,
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new CliError("NETWORK", `Could not reach ${url}: ${reason}`, EXIT.network);
+  }
+}
+function authHeaders(credentials) {
+  return {
+    authorization: `Bearer ${credentials.apiKey}`,
+    "user-agent": `aeosome-cli/${VERSION}`,
+    accept: "application/json"
+  };
+}
+async function getJson(credentials, path) {
+  const response = await send(`${credentials.apiUrl}${path}`, {
+    headers: authHeaders(credentials)
+  });
+  const body = await parse(response);
+  if (!response.ok)
+    throw failureFor(response.status, body);
+  return body;
+}
+
+// ../../packages/agent-tools/src/types.ts
+var DAYS = {
+  name: "days",
+  description: "Look-back window in days (default 30). The plan's history limit caps it.",
+  type: "integer",
+  in: "query",
+  minimum: 1,
+  maximum: 365
+};
+var PAGE = {
+  name: "page",
+  description: "Page number, from 1.",
+  type: "integer",
+  in: "query",
+  minimum: 1
+};
+var LIMIT = {
+  name: "limit",
+  description: "Rows per page (default 20, max 100).",
+  type: "integer",
+  in: "query",
+  minimum: 1,
+  maximum: 100
+};
+var id = (description) => ({
+  name: "id",
+  description,
+  type: "string",
+  in: "path",
+  required: true
+});
+var PERIOD = ["period.days", "Period (days)"];
+
+// ../../packages/agent-tools/src/tools-actions.ts
+var ACTION_TOOLS = [
+  {
+    name: "get_competitor_leaderboard",
+    command: "competitors",
+    description: "Competitors ranked by share of voice in AI answers, with prompts won and citation share.",
+    path: "/api/competitor-analytics/leaderboard",
+    params: [DAYS],
+    view: {
+      headline: [PERIOD, ["dataSignals.totalRuns", "Answers analysed"]],
+      table: {
+        rows: "rows",
+        columns: [
+          ["name", "Brand"],
+          ["isOwn", "You"],
+          ["shareOfVoice", "Share of voice (%)"],
+          ["promptsWon", "Questions won"],
+          ["citationShare", "Citation share (%)"]
+        ]
+      }
+    }
+  },
+  {
+    name: "get_citation_sources",
+    command: "citations",
+    description: "The domains AI engines cite most in answers about the store's products.",
+    path: "/api/citations/stats",
+    params: [],
+    view: {
+      headline: [
+        ["totalCitations", "Citations"],
+        ["uniqueDomains", "Domains"],
+        ["ownDomainCount", "Citations of your domain"]
+      ],
+      table: {
+        rows: "topDomains",
+        columns: [
+          ["domain", "Domain"],
+          ["count", "Citations"]
+        ]
+      }
+    }
+  },
+  {
+    name: "get_citation_opportunities",
+    command: "opportunities",
+    description: "Sites that AI engines cite for competitors but never for the store: the outreach list.",
+    path: "/api/citation-analytics/opportunities",
+    params: [DAYS],
+    view: {
+      headline: [PERIOD],
+      table: {
+        rows: "opportunities",
+        columns: [
+          ["domain", "Domain"],
+          ["domainType", "Type"],
+          ["competitorMentions", "Competitor citations"],
+          ["topCompetitor.name", "Top competitor"]
+        ]
+      }
+    }
+  },
+  {
+    name: "list_recommendations",
+    command: "fixes",
+    description: "Fixes to raise AI visibility, with priority, expected impact and step-by-step implementation guides.",
+    path: "/api/recommendations",
+    params: [
+      PAGE,
+      LIMIT,
+      {
+        name: "status",
+        description: "Filter by status.",
+        type: "string",
+        in: "query",
+        enum: ["pending", "applied", "dismissed"]
+      },
+      {
+        name: "priority",
+        description: "Filter by priority.",
+        type: "string",
+        in: "query",
+        enum: ["critical", "high", "medium", "low"]
+      }
+    ],
+    view: {
+      headline: [
+        ["total", "Fixes"],
+        ["locked", "Fixes locked by plan"]
+      ],
+      table: {
+        rows: "items",
+        columns: [
+          ["priority", "Priority"],
+          ["status", "Status"],
+          ["recommendationText", "Fix"],
+          ["expectedImpact", "Expected impact"]
+        ]
+      }
+    }
+  },
+  {
+    name: "get_improvement_summary",
+    command: "progress",
+    description: "Open issues by category, fixes applied in the last 7 and 30 days, and the measured visibility change after fixes.",
+    path: "/api/improve/summary",
+    params: [DAYS],
+    view: {
+      headline: [
+        PERIOD,
+        ["applied.appliedLast7d", "Fixes applied (7 days)"],
+        ["applied.appliedLast30d", "Fixes applied (30 days)"],
+        ["verification.totalVerified", "Fixes verified"],
+        [
+          "verification.avgVisibilityDelta",
+          "Avg visibility change after a fix (points)"
+        ]
+      ],
+      table: {
+        rows: "issues",
+        columns: [
+          ["category", "Category"],
+          ["openCount", "Open issues"],
+          ["productsAffected", "Products affected"]
+        ]
+      }
+    }
+  },
+  {
+    name: "list_alerts",
+    command: "alerts",
+    description: "Recent alerts: visibility drops, new competitors, and findings.",
+    path: "/api/alerts",
+    params: [PAGE, LIMIT],
+    view: {
+      headline: [["total", "Unread alerts"]],
+      table: {
+        rows: "alerts",
+        columns: [
+          ["triggeredAt", "When"],
+          ["severity", "Severity"],
+          ["title", "Alert"]
+        ]
+      }
+    }
+  },
+  {
+    name: "get_usage",
+    command: "usage",
+    description: "Plan limits and current usage: products, answers this month, team seats and the billing period end.",
+    path: "/api/usage",
+    params: [],
+    view: {
+      headline: [
+        ["planName", "Plan"],
+        ["productsTracked.used", "Products tracked"],
+        ["productsTracked.limit", "Product limit"],
+        ["monthlyResponses.used", "Answers this month"],
+        ["monthlyResponses.derivedCap", "Answer limit per month"],
+        ["teamMembers.used", "Team members"],
+        ["teamMembers.limit", "Team member limit"],
+        ["periodEnd", "Period ends"]
+      ]
+    }
+  }
+];
+
+// ../../packages/agent-tools/src/tools-visibility.ts
+var VISIBILITY_TOOLS = [
+  {
+    name: "whoami",
+    command: "whoami",
+    description: "The workspace and plan this API key belongs to.",
+    path: "/api/api-keys/current",
+    params: [],
+    view: {
+      headline: [
+        ["organization.name", "Workspace"],
+        ["plan", "Plan"]
+      ]
+    }
+  },
+  {
+    name: "get_brief",
+    command: "brief",
+    description: "One-paragraph status of the store's AI visibility this week: what slipped, which rival is named instead, and what changed.",
+    path: "/api/insights/brief",
+    params: [],
+    view: {
+      headline: [
+        ["status.sentence", "Status"],
+        ["status.period", "Period"],
+        ["questions.asked", "Shopper questions asked"],
+        ["questions.shownIn", "Questions that showed the store"],
+        ["rival.name", "Rival named most instead"]
+      ],
+      table: { rows: "changes", columns: [["text", "Change"]] }
+    }
+  },
+  {
+    name: "get_dashboard",
+    command: "dashboard",
+    description: "Headline AI visibility KPIs with trend against the prior period: visibility, top-3 presence, share of voice, citation health, shopping appearance.",
+    path: "/api/analytics/dashboard",
+    params: [DAYS],
+    view: {
+      headline: [
+        PERIOD,
+        ["kpis.aiVisibility.value", "AI visibility (% of answers)"],
+        ["kpis.aiVisibility.trend", "AI visibility change (points)"],
+        ["kpis.top3Presence.value", "Top-3 presence (% of answers)"],
+        ["kpis.shareOfVoice.value", "Share of voice (%)"],
+        ["kpis.shoppingAppearance.value", "Shopping appearance (% of answers)"],
+        ["dataSignals.totalRuns", "Answers analysed"],
+        ["dataSignals.productsTracked", "Products tracked"]
+      ]
+    }
+  },
+  {
+    name: "get_share_of_voice",
+    command: "share-of-voice",
+    description: "Share of brand mentions in AI answers against competitors, optionally for one engine.",
+    path: "/api/analytics/share-of-voice",
+    params: [
+      DAYS,
+      {
+        name: "engine",
+        description: "One engine id: chatgpt or google_ai_mode.",
+        type: "string",
+        in: "query"
+      }
+    ],
+    view: {
+      headline: [
+        ["shareOfVoice", "Share of voice (%)"],
+        ["brandMentions", "Brand mentions (answers)"],
+        ["competitorMentions", "Competitor mentions (answers)"],
+        ["totalResults", "Answers analysed"]
+      ],
+      table: {
+        rows: "topCompetitors",
+        columns: [
+          ["name", "Competitor"],
+          ["mentions", "Mentions"],
+          ["shareOfVoice", "Share (%)"]
+        ]
+      }
+    }
+  },
+  {
+    name: "list_products",
+    command: "products",
+    description: "Tracked products with their store URLs.",
+    path: "/api/products",
+    params: [PAGE, LIMIT],
+    view: {
+      headline: [["total", "Products"]],
+      table: {
+        rows: "items",
+        columns: [
+          ["id", "ID"],
+          ["title", "Title"],
+          ["url", "URL"]
+        ]
+      }
+    }
+  },
+  {
+    name: "list_prompts",
+    command: "prompts",
+    description: "Shopper questions sent to AI engines, whether the store was named, and which engines showed it. Use a question id with get_prompt_responses.",
+    path: "/api/prompts",
+    params: [
+      DAYS,
+      PAGE,
+      LIMIT,
+      {
+        name: "missingBrand",
+        description: '"true" to list only questions where the store was not named.',
+        type: "string",
+        in: "query",
+        enum: ["true", "false"]
+      },
+      {
+        name: "productId",
+        description: "Only questions for this product id.",
+        type: "string",
+        in: "query"
+      }
+    ],
+    view: {
+      headline: [["total", "Questions"]],
+      table: {
+        rows: "items",
+        columns: [
+          ["generatedQueryIds.0", "Question ID"],
+          ["queryText", "Question"],
+          ["brandMentioned", "Named"],
+          ["visibility", "Visibility (%)"],
+          ["executionCount", "Answers"]
+        ]
+      }
+    }
+  },
+  {
+    name: "get_prompt_responses",
+    command: "responses",
+    description: "The full AI answers to one shopper question, per engine, with the products and sources each answer cited.",
+    path: "/api/prompts/{id}/responses",
+    params: [id("Question id from list_prompts (generatedQueryIds[0]).")],
+    view: {
+      headline: [
+        ["queryText", "Question"],
+        ["productTitle", "Product"]
+      ],
+      table: {
+        rows: "responses",
+        columns: [
+          ["platform", "Engine"],
+          ["executedAt", "Asked at"],
+          ["rawResponseText", "Answer"]
+        ]
+      }
+    }
+  }
+];
+
+// ../../packages/agent-tools/src/catalog.ts
+var AGENT_TOOLS = [
+  ...VISIBILITY_TOOLS,
+  ...ACTION_TOOLS
+];
+function findTool(nameOrCommand) {
+  return AGENT_TOOLS.find((t) => t.name === nameOrCommand || t.command === nameOrCommand);
+}
+
+// ../../packages/agent-tools/src/request.ts
+class ToolArgError extends Error {
+}
+function inRange(p, n) {
+  const min = p.minimum ?? Number.NEGATIVE_INFINITY;
+  const max = p.maximum ?? Number.POSITIVE_INFINITY;
+  return Number.isInteger(n) && n >= min && n <= max;
+}
+var isOutOfRange = (p, value) => p.type === "integer" && !inRange(p, Number(value));
+var isOffEnum = (p, value) => p.enum !== undefined && !p.enum.includes(value);
+function checkValue(p, value) {
+  if (isOutOfRange(p, value))
+    throw new ToolArgError(`${p.name} must be a whole number in range`);
+  if (isOffEnum(p, value))
+    throw new ToolArgError(`${p.name} must be one of ${p.enum?.join(", ")}`);
+}
+var isBlank = (raw) => raw === undefined || raw === null || raw === "";
+function argValue(p, args) {
+  const raw = args[p.name];
+  if (isBlank(raw) && p.required)
+    throw new ToolArgError(`${p.name} is required`);
+  if (isBlank(raw))
+    return;
+  const value = String(raw);
+  checkValue(p, value);
+  return value;
+}
+function rejectUnknown(tool, args) {
+  const known = new Set(tool.params.map((p) => p.name));
+  const unknown = Object.keys(args).filter((k) => !known.has(k));
+  if (unknown.length > 0)
+    throw new ToolArgError(`Unknown argument: ${unknown.join(", ")}`);
+}
+function fillPath(tool, values) {
+  return tool.params.filter((p) => p.in === "path").reduce((path, p) => path.replace(`{${p.name}}`, encodeURIComponent(values.get(p.name) ?? "")), tool.path);
+}
+function collectValues(tool, args) {
+  const entries = tool.params.map((p) => [p.name, argValue(p, args)]).filter((e) => e[1] !== undefined);
+  return new Map(entries);
+}
+function buildToolPath(tool, args = {}) {
+  rejectUnknown(tool, args);
+  const values = collectValues(tool, args);
+  const query = new URLSearchParams(tool.params.filter((p) => p.in === "query" && values.has(p.name)).map((p) => [p.name, values.get(p.name) ?? ""])).toString();
+  const path = fillPath(tool, values);
+  return query ? `${path}?${query}` : path;
+}
+function readField(data, path) {
+  return path.split(".").reduce((current, key) => current !== null && typeof current === "object" ? current[key] : undefined, data);
+}
+
+// src/config.ts
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_API_URL = "https://api.aeosome.com";
+function credentialsPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "aeosome", "credentials.json");
+}
+async function readSaved(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function loadCredentials(env = process.env) {
+  const saved = await readSaved(credentialsPath(env));
+  return {
+    apiKey: env.AEOSOME_API_KEY || saved.apiKey,
+    apiUrl: env.AEOSOME_API_URL || saved.apiUrl || DEFAULT_API_URL
+  };
+}
+async function saveCredentials(credentials, env = process.env) {
+  const path = credentialsPath(env);
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, `${JSON.stringify(credentials, null, 2)}
+`, {
+    mode: 384
+  });
+  return path;
+}
+async function clearCredentials(env = process.env) {
+  await rm(credentialsPath(env), { force: true });
+}
+
+// src/mcp-bridge.ts
+import { createInterface } from "node:readline";
+var idOf = (line) => {
+  try {
+    return JSON.parse(line).id;
+  } catch {
+    return null;
+  }
+};
+function rpcError(id2, message) {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id: id2 ?? null,
+    error: { code: -32000, message }
+  });
+}
+async function errorText(response) {
+  const body = await response.json().catch(() => ({}));
+  return body.message ?? body.error ?? `HTTP ${response.status}`;
+}
+function post(credentials, line) {
+  return fetch(`${credentials.apiUrl}/mcp`, {
+    method: "POST",
+    headers: {
+      ...authHeaders(credentials),
+      "content-type": "application/json"
+    },
+    body: line,
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+}
+async function replyFor(response, id2) {
+  if (response.status === 202)
+    return null;
+  if (response.ok)
+    return response.text();
+  return id2 === undefined ? null : rpcError(id2, await errorText(response));
+}
+async function relay(credentials, line, write) {
+  const id2 = idOf(line);
+  const reply = await post(credentials, line).then((response) => replyFor(response, id2)).catch((error) => id2 === undefined ? null : rpcError(id2, String(error)));
+  if (reply)
+    write(reply);
+}
+async function runBridge(credentials) {
+  const write = (line) => process.stdout.write(`${line.trim()}
+`);
+  const pending = [];
+  for await (const line of createInterface({ input: process.stdin })) {
+    if (line.trim())
+      pending.push(relay(credentials, line, write));
+  }
+  await Promise.all(pending);
+}
+
+// src/prompt.ts
+import { createInterface as createInterface2 } from "node:readline";
+import { Writable } from "node:stream";
+var silent = new Writable({ write: (_chunk, _encoding, done) => done() });
+async function readPiped() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readHidden() {
+  const rl = createInterface2({
+    input: process.stdin,
+    output: silent,
+    terminal: true
+  });
+  try {
+    return await new Promise((resolve) => rl.question("", resolve));
+  } finally {
+    rl.close();
+    process.stderr.write(`
+`);
+  }
+}
+async function readSecret(question) {
+  process.stderr.write(question);
+  const text = await (process.stdin.isTTY ? readHidden() : readPiped());
+  return text.trim();
+}
+
+// src/render.ts
+var MIN_COLUMN = 8;
+var GAP = "  ";
+var formatText = (value) => String(value).replace(/\s+/g, " ").trim();
+var FORMATTERS = {
+  boolean: (value) => value ? "yes" : "no",
+  object: (value) => JSON.stringify(value)
+};
+function formatValue(value) {
+  if (value === null || value === undefined)
+    return "-";
+  return (FORMATTERS[typeof value] ?? formatText)(value);
+}
+function clip(text, width) {
+  return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
+function renderHeadline(fields, data) {
+  const pad = Math.max(...fields.map(([, label]) => label.length));
+  return fields.map(([path, label]) => `${label.padEnd(pad)}  ${formatValue(readField(data, path))}`);
+}
+function columnWidths(cells, width) {
+  const count = cells[0]?.length ?? 1;
+  const budget = Math.max(MIN_COLUMN, Math.floor((width - GAP.length * (count - 1)) / count));
+  return (cells[0] ?? []).map((_, c) => Math.min(budget, Math.max(...cells.map((row) => row[c]?.length ?? 0))));
+}
+function renderTable(columns, rows, width) {
+  const header = columns.map(([, label]) => label);
+  const body = rows.map((row) => columns.map(([path]) => formatValue(readField(row, path))));
+  const cells = [header, ...body];
+  const widths = columnWidths(cells, width);
+  return cells.map((row) => row.map((cell, c) => clip(cell, widths[c] ?? MIN_COLUMN).padEnd(widths[c] ?? 0)).join(GAP).trimEnd());
+}
+function tableLines(tool, data, width) {
+  const table = tool.view.table;
+  if (!table)
+    return [];
+  const rows = readField(data, table.rows);
+  if (!Array.isArray(rows) || rows.length === 0)
+    return ["", "No rows."];
+  return ["", ...renderTable(table.columns, rows, width)];
+}
+function renderHuman(tool, data, width = 100) {
+  const headline = tool.view.headline ?? [];
+  return [...renderHeadline(headline, data), ...tableLines(tool, data, width)].join(`
+`).trim();
+}
+
+// src/commands.ts
+var flagName = (name) => name.replace(/([A-Z])/g, "-$1").toLowerCase();
+function toolUsage(tool) {
+  const flags = tool.params.map((p) => p.in === "path" ? `<${p.name}>` : `[--${flagName(p.name)} <${p.type}>]`).join(" ");
+  return `  ${`${tool.command} ${flags}`.padEnd(58)} ${tool.description.split(". ")[0]}`;
+}
+function helpText() {
+  return [
+    `aeosome ${VERSION}: your AI visibility data from a terminal, a script or an agent.`,
+    "",
+    "Usage: aeosome <command> [flags] [--json]",
+    "",
+    "Account:",
+    "  login                                                      Save an API key (Settings, Integrations, API access)",
+    "  logout                                                     Forget the saved key",
+    "  tools                                                      List data commands as JSON-ready metadata",
+    "  mcp                                                        Run a stdio MCP server for Claude Desktop, Cursor and others",
+    "",
+    "Data (read-only):",
+    ...AGENT_TOOLS.map(toolUsage),
+    "",
+    "Flags: --json prints the API response as JSON on stdout. Errors go to stderr.",
+    "Env:   AEOSOME_API_KEY and AEOSOME_API_URL override the saved login.",
+    "Exit:  0 ok, 1 usage, 2 not signed in, 3 needs a paid plan, 4 API error, 5 network."
+  ].join(`
+`);
+}
+async function requireCredentials() {
+  const creds = await loadCredentials();
+  if (!creds.apiKey)
+    throw new CliError("UNAUTHORIZED", "Not signed in. Run `aeosome login` or set AEOSOME_API_KEY.", EXIT.auth);
+  return creds;
+}
+function emit(io, tool, data) {
+  io.out(io.json ? JSON.stringify(data, null, 2) : renderHuman(tool, data, io.width));
+}
+function flagArgs(tool, flags) {
+  const known = new Map(tool.params.map((p) => [flagName(p.name), p.name]));
+  const asArg = (value) => value === true ? "true" : value;
+  return Object.fromEntries([...flags].filter(([flag]) => flag !== "json").map(([flag, value]) => [known.get(flag) ?? flag, asArg(value)]));
+}
+function toolArgs(tool, args) {
+  const result = flagArgs(tool, args.flags);
+  const pathParam = tool.params.find((p) => p.in === "path");
+  const positional = args.positionals[0];
+  if (!pathParam || !positional)
+    return result;
+  return { ...result, [pathParam.name]: positional };
+}
+function pathFor(tool, args) {
+  try {
+    return buildToolPath(tool, toolArgs(tool, args));
+  } catch (error) {
+    if (error instanceof ToolArgError)
+      throw new CliError("USAGE", `${error.message}
+${toolUsage(tool).trim()}`, EXIT.usage);
+    throw error;
+  }
+}
+async function runTool(tool, args, io) {
+  const path = pathFor(tool, args);
+  emit(io, tool, await getJson(await requireCredentials(), path));
+}
+async function keyFromEnvOrPrompt() {
+  const apiKey = process.env.AEOSOME_API_KEY || await readSecret("API key (aeo_...): ");
+  if (!apiKey.startsWith("aeo_"))
+    throw new CliError("USAGE", "That is not an aeosome API key; it starts with aeo_.", EXIT.usage);
+  return apiKey;
+}
+async function login(io) {
+  const { apiUrl = "" } = await loadCredentials();
+  const creds = { apiKey: await keyFromEnvOrPrompt(), apiUrl };
+  const me = await getJson(creds, "/api/api-keys/current");
+  const savedTo = await saveCredentials(creds);
+  const sentence = `Signed in to ${me.organization.name} (${me.plan}). Key saved to ${savedTo}`;
+  io.out(io.json ? JSON.stringify({ ...me, savedTo }) : sentence);
+}
+async function logout(io) {
+  await clearCredentials();
+  io.out(io.json ? JSON.stringify({ signedOut: true }) : "Signed out.");
+}
+function tools(io) {
+  const list = AGENT_TOOLS.map(({ name, command, description, params }) => ({
+    name,
+    command,
+    description,
+    params
+  }));
+  io.out(io.json ? JSON.stringify(list, null, 2) : AGENT_TOOLS.map(toolUsage).join(`
+`));
+}
+var ACCOUNT = {
+  login,
+  logout,
+  tools,
+  mcp: async () => runBridge(await requireCredentials()),
+  help: (io) => io.out(helpText()),
+  version: (io) => io.out(VERSION)
+};
+var commandName = (args) => args.flags.has("version") ? "version" : args.command ?? "help";
+function resolveTool(command) {
+  const tool = findTool(command);
+  if (!tool)
+    throw new CliError("USAGE", `Unknown command: ${command}. Run \`aeosome help\`.`, EXIT.usage);
+  return tool;
+}
+async function run(args, io) {
+  const command = commandName(args);
+  const account = args.flags.has("help") ? ACCOUNT.help : ACCOUNT[command];
+  if (account)
+    return account(io);
+  return runTool(resolveTool(command), args, io);
+}
+
+// src/index.ts
+var args = parseArgs(process.argv.slice(2));
+var json = args.flags.has("json");
+var codeOf = (error) => error instanceof CliError ? error.code : "INTERNAL";
+var exitOf = (error) => error instanceof CliError ? error.exitCode : EXIT.api;
+var messageOf2 = (error) => error instanceof Error ? error.message : String(error);
+function fail(error) {
+  const payload = { error: { code: codeOf(error), message: messageOf2(error) } };
+  if (json)
+    process.stdout.write(`${JSON.stringify(payload)}
+`);
+  else
+    process.stderr.write(`error: ${payload.error.message}
+`);
+  process.exitCode = exitOf(error);
+}
+await run(args, {
+  out: (text) => process.stdout.write(`${text}
+`),
+  json,
+  width: process.stdout.columns ?? 100
+}).catch(fail);

package/package.json

@@ -1,6 +1,31 @@
 {
-  "name": "@aeosome/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@aeosome/cli",
+	"version": "0.1.0",
+	"description": "Read your aeosome AI visibility data from a terminal, a script or an AI agent.",
+	"type": "module",
+	"license": "UNLICENSED",
+	"homepage": "https://aeosome.com",
+	"bin": {
+		"aeosome": "dist/aeosome.js"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"devDependencies": {
+		"@repo/agent-tools": "^0.0.1",
+		"@repo/biome-config": "^0.0.0",
+		"@repo/tier-config": "^0.0.1",
+		"@repo/typescript-config": "^0.0.0",
+		"@types/bun": "latest",
+		"typescript": "^5.7.3"
+	},
+	"scripts": {
+		"build": "bun build src/index.ts --target node --outfile dist/aeosome.js",
+		"check": "biome check .",
+		"check-types": "tsc --noEmit",
+		"test": "bun test --timeout 30000"
+	}
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.