databull 1.0.0 → 1.1.0

package/dist/databull.mjs

@@ -172,13 +172,17 @@ var Cancelled = class extends Error {
 var SUPPORT = "adgan.business@gmail.com";
 
 // src/args.mjs
-var COMMANDS = ["install", "update", "reset-password", "domain", "status", "license", "uninstall", "help"];
-var COMMAND_ALIASES = { license: "license", "reset": "reset-password", upgrade: "update", remove: "uninstall" };
-var VALUE_FLAGS = ["key", "account", "name", "domain", "api", "bundle", "home"];
-var BOOL_FLAGS = ["yes", "open", "help", "version", "deactivate", "delete-database", "debug"];
-var SHORT = { y: "yes", h: "help", v: "version" };
+var DATA_COMMANDS = ["sites", "stats", "sources", "breakdown", "compare", "sales", "visitors", "visitor", "live", "goals", "funnels", "ltv", "query"];
+var COMMANDS = ["install", "update", "reset-password", "domain", "status", "license", "uninstall", "mcp", "api-key", ...DATA_COMMANDS, "help"];
+var TAKES_ARGS = /* @__PURE__ */ new Set(["api-key", ...DATA_COMMANDS]);
+var COMMAND_ALIASES = { license: "license", "reset": "reset-password", upgrade: "update", remove: "uninstall", "api-keys": "api-key", keys: "api-key", key: "api-key", overview: "stats", referrers: "sources", realtime: "live", payments: "sales" };
+var VALUE_FLAGS = ["key", "account", "name", "domain", "api", "bundle", "home", "period", "from", "to", "site", "limit", "by", "dim", "sort", "url", "api-key", "client", "funnel", "page", "label"];
+var MULTI_FLAGS = ["filter"];
+var BOOL_FLAGS = ["yes", "open", "help", "version", "deactivate", "delete-database", "debug", "json", "pii", "customers", "series"];
+var SHORT = { y: "yes", h: "help", v: "version", p: "period", s: "site", n: "limit", f: "filter" };
+var SHORT_VALUE = /* @__PURE__ */ new Set(["p", "s", "n", "f"]);
 function parseArgs(argv) {
-  const out2 = { command: null, flags: { open: true } };
+  const out3 = { command: null, flags: { open: true }, args: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--") continue;
@@ -186,41 +190,55 @@ function parseArgs(argv) {
       let [name, value] = splitOnce(arg.slice(2), "=");
       if (name.startsWith("no-") && BOOL_FLAGS.includes(name.slice(3))) {
         if (value !== void 0) throw new Fail(`--${name} doesn't take a value.`);
-        out2.flags[name.slice(3)] = false;
+        out3.flags[name.slice(3)] = false;
         continue;
       }
       if (BOOL_FLAGS.includes(name)) {
         if (value !== void 0) throw new Fail(`--${name} doesn't take a value.`);
-        out2.flags[camel(name)] = true;
+        out3.flags[camel(name)] = true;
         continue;
       }
-      if (VALUE_FLAGS.includes(name)) {
+      if (VALUE_FLAGS.includes(name) || MULTI_FLAGS.includes(name)) {
         if (value === void 0) {
           value = argv[i + 1];
           if (value === void 0 || value.startsWith("--")) throw new Fail(`--${name} needs a value.`, { fix: `Example: --${name} ${example(name)}` });
           i++;
         }
-        out2.flags[name] = value;
+        if (MULTI_FLAGS.includes(name)) (out3.flags[name] ||= []).push(value);
+        else out3.flags[name === "api-key" ? "apiKey" : name] = value;
         continue;
       }
       throw new Fail(`Unknown option --${name}.`, { fix: "Run `npx databull@latest help` to see every option." });
     }
-    if (arg.startsWith("-") && arg.length > 1) {
-      for (const ch of arg.slice(1)) {
-        if (!SHORT[ch]) throw new Fail(`Unknown option -${ch}.`, { fix: "Run `npx databull@latest help` to see every option." });
-        out2.flags[SHORT[ch]] = true;
+    if (arg.startsWith("-") && arg.length > 1 && !/^-\d/.test(arg)) {
+      const letters = arg.slice(1);
+      if (letters.length === 1 && SHORT_VALUE.has(letters)) {
+        const v2 = argv[i + 1];
+        if (v2 === void 0 || v2.startsWith("-")) throw new Fail(`-${letters} needs a value.`, { fix: `Example: -${letters} ${example(SHORT[letters])}` });
+        i++;
+        if (MULTI_FLAGS.includes(SHORT[letters])) (out3.flags[SHORT[letters]] ||= []).push(v2);
+        else out3.flags[SHORT[letters]] = v2;
+        continue;
+      }
+      for (const ch of letters) {
+        if (!SHORT[ch] || SHORT_VALUE.has(ch)) throw new Fail(`Unknown option -${ch}.`, { fix: "Run `npx databull@latest help` to see every option." });
+        out3.flags[SHORT[ch]] = true;
       }
       continue;
     }
-    if (out2.command) throw new Fail(`Unexpected "${arg}".`, { fix: "Run `npx databull@latest help` to see every command." });
+    if (out3.command && TAKES_ARGS.has(out3.command)) {
+      out3.args.push(arg);
+      continue;
+    }
+    if (out3.command) throw new Fail(`Unexpected "${arg}".`, { fix: "Run `npx databull@latest help` to see every command." });
     const cmd = COMMAND_ALIASES[arg] || arg;
     if (!COMMANDS.includes(cmd)) throw new Fail(`Unknown command "${arg}".`, { fix: `Commands: ${COMMANDS.join(", ")}.` });
-    out2.command = cmd;
+    out3.command = cmd;
   }
-  if (out2.flags.help) out2.command = "help";
-  else if (out2.flags.version) out2.command = "version";
-  else if (!out2.command) out2.command = "install";
-  return out2;
+  if (out3.flags.help) out3.command = "help";
+  else if (out3.flags.version) out3.command = "version";
+  else if (!out3.command) out3.command = "install";
+  return out3;
 }
 function splitOnce(s, sep) {
   const i = s.indexOf(sep);
@@ -230,7 +248,30 @@ function camel(s) {
   return s.replace(/-([a-z])/g, (_3, c) => c.toUpperCase());
 }
 function example(name) {
-  return { key: "XXXX-XXXX", account: "<account id>", name: "databull", domain: "analytics.example.com", api: "https://databull.app", bundle: "./databull-1.0.0.tgz", home: "~/.databull" }[name];
+  return {
+    key: "XXXX-XXXX",
+    account: "<account id>",
+    name: "databull",
+    domain: "analytics.example.com",
+    api: "https://databull.app",
+    bundle: "./databull-1.0.0.tgz",
+    home: "~/.databull",
+    period: "7d",
+    from: "2026-10-01",
+    to: "2026-10-31",
+    site: "example.com",
+    limit: "20",
+    by: "revenue",
+    dim: "referrer",
+    sort: "revenue",
+    url: "https://analytics.example.com",
+    "api-key": "dbk_\u2026",
+    client: "claude",
+    funnel: "Checkout",
+    page: "1",
+    label: '"CI"',
+    filter: "country=US"
+  }[name];
 }
 
 // src/config.mjs
@@ -289,6 +330,11 @@ function upsertInstall(cfg, install) {
   else cfg.installs.push(install);
   return cfg;
 }
+function forgetInstallFields(cfg, install, fields) {
+  const saved = cfg.installs.find((i) => i.name === install.name && i.account_id === install.account_id);
+  if (saved) for (const f of fields) delete saved[f];
+  return cfg;
+}
 function removeInstall(cfg, install) {
   cfg.installs = cfg.installs.filter((i) => !(i.name === install.name && i.account_id === install.account_id));
   return cfg;
@@ -1069,6 +1115,10 @@ function info(text) {
   out.write(`${import_picocolors3.default.blue("\u25CF")}  ${text}
 `);
 }
+function success(text) {
+  out.write(`${import_picocolors3.default.green("\u25C6")}  ${text}
+`);
+}
 function warn(text, fix) {
   out.write(`${import_picocolors3.default.yellow("\u25B2")}  ${text}
 `);
@@ -1156,8 +1206,8 @@ function stopSpinner() {
   if (activeSpinner) activeSpinner.fail(import_picocolors3.default.dim("Stopped"));
 }
 function box(title, lines, { color = import_picocolors3.default.blue } = {}) {
-  const strip = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
-  const width = Math.max(strip(title).length + 2, ...lines.map((l2) => strip(l2).length)) + 2;
+  const strip2 = (s) => s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+  const width = Math.max(strip2(title).length + 2, ...lines.map((l2) => strip2(l2).length)) + 2;
   if (isTTY() && out.columns && width + 2 > out.columns) {
     out.write(`${BAR}
 ${color("\u256D\u2500")} ${import_picocolors3.default.bold(title)}
@@ -1169,9 +1219,9 @@ ${color("\u256D\u2500")} ${import_picocolors3.default.bold(title)}
     return;
   }
   out.write(`${BAR}
-${color("\u256D")}${color("\u2500")} ${import_picocolors3.default.bold(title)} ${color("\u2500".repeat(Math.max(0, width - strip(title).length - 3)))}${color("\u256E")}
+${color("\u256D")}${color("\u2500")} ${import_picocolors3.default.bold(title)} ${color("\u2500".repeat(Math.max(0, width - strip2(title).length - 3)))}${color("\u256E")}
 `);
-  for (const l2 of lines) out.write(`${color("\u2502")} ${l2}${" ".repeat(Math.max(0, width - strip(l2).length - 1))}${color("\u2502")}
+  for (const l2 of lines) out.write(`${color("\u2502")} ${l2}${" ".repeat(Math.max(0, width - strip2(l2).length - 1))}${color("\u2502")}
 `);
   out.write(`${color("\u2570")}${color("\u2500".repeat(width))}${color("\u256F")}
 `);
@@ -1285,16 +1335,16 @@ async function cf(ctx, method, path7, body) {
   });
 }
 async function cfList(ctx, path7, perPage = 50) {
-  const out2 = [];
+  const out3 = [];
   for (let page = 1; page < 50; page++) {
     const sep = path7.includes("?") ? "&" : "?";
     const json2 = await cf(ctx, "GET", `${path7}${sep}page=${page}&per_page=${perPage}`);
-    out2.push(...json2.result || []);
+    out3.push(...json2.result || []);
     const info2 = json2.result_info;
     if (!info2 || !Array.isArray(json2.result) || json2.result.length < perPage) break;
     if (info2.total_pages && page >= info2.total_pages) break;
   }
-  return out2;
+  return out3;
 }
 async function whoami(ctx) {
   const r2 = await runWrangler(ctx, ["whoami", "--json"], { title: "whoami --json" });
@@ -1558,10 +1608,10 @@ function octal(buf, start, len) {
   if (!/^[0-7]+$/.test(s)) throw new TarError("corrupt tar header");
   return parseInt(s, 8);
 }
-function checksumOk(header) {
-  const stored = octal(header, 148, 8);
+function checksumOk(header2) {
+  const stored = octal(header2, 148, 8);
   let sum = 0;
-  for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 32 : header[i];
+  for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 32 : header2[i];
   return sum === stored;
 }
 function safePath(name) {
@@ -1576,7 +1626,7 @@ function safePath(name) {
   return parts.join("/");
 }
 function parsePax(data) {
-  const out2 = {};
+  const out3 = {};
   let i = 0;
   const text = data.toString("utf8");
   while (i < text.length) {
@@ -1586,10 +1636,10 @@ function parsePax(data) {
     if (!len) break;
     const record = text.slice(sp + 1, i + len - 1);
     const eq = record.indexOf("=");
-    if (eq > 0) out2[record.slice(0, eq)] = record.slice(eq + 1);
+    if (eq > 0) out3[record.slice(0, eq)] = record.slice(eq + 1);
     i += len;
   }
-  return out2;
+  return out3;
 }
 function readTar(input) {
   const buf = input[0] === 31 && input[1] === 139 ? gunzipSync(input) : input;
@@ -1598,11 +1648,11 @@ function readTar(input) {
   let longName = null;
   let pax = null;
   while (off + BLOCK <= buf.length) {
-    const header = buf.subarray(off, off + BLOCK);
-    if (header.every((b3) => b3 === 0)) break;
-    if (!checksumOk(header)) throw new TarError("corrupt tar header (bad checksum)");
-    const size = octal(header, 124, 12);
-    const type = String.fromCharCode(header[156] || 48);
+    const header2 = buf.subarray(off, off + BLOCK);
+    if (header2.every((b3) => b3 === 0)) break;
+    if (!checksumOk(header2)) throw new TarError("corrupt tar header (bad checksum)");
+    const size = octal(header2, 124, 12);
+    const type = String.fromCharCode(header2[156] || 48);
     const dataStart = off + BLOCK;
     if (dataStart + size > buf.length) throw new TarError("truncated tar archive");
     const data = buf.subarray(dataStart, dataStart + size);
@@ -1616,9 +1666,9 @@ function readTar(input) {
       continue;
     }
     if (type === "g") continue;
-    let name = str(header, 0, 100);
-    if (str(header, 257, 5) === "ustar") {
-      const prefix = str(header, 345, 155);
+    let name = str(header2, 0, 100);
+    if (str(header2, 257, 5) === "ustar") {
+      const prefix = str(header2, 345, 155);
       if (prefix) name = `${prefix}/${name}`;
     }
     if (pax?.path) name = pax.path;
@@ -2127,7 +2177,7 @@ async function discoverInstalls(ctx, account, onlyName) {
     }
   };
   await Promise.all(Array.from({ length: 8 }, worker));
-  const out2 = [];
+  const out3 = [];
   for (const f of found.sort((a, b3) => a.name.localeCompare(b3.name))) {
     const settings = await workerSettings(ctx, account.id, f.name).catch(() => ({}));
     const bindings = settings.bindings || [];
@@ -2146,7 +2196,7 @@ async function discoverInstalls(ctx, account, onlyName) {
     }
     const domains = await customDomainsOf(ctx, account.id, f.name);
     const custom = domains[0] || null;
-    out2.push({
+    out3.push({
       name: f.name,
       account_id: account.id,
       account_name: account.name,
@@ -2162,7 +2212,7 @@ async function discoverInstalls(ctx, account, onlyName) {
       updated_at: null
     });
   }
-  return out2;
+  return out3;
 }
 async function pickDiscovered(ctx, found, verb) {
   if (ctx.flags.name) return found.find((f2) => f2.name === ctx.flags.name) || null;
@@ -2782,20 +2832,686 @@ async function runUninstall(ctx) {
   end("Done.");
 }
 
+// src/agent.mjs
+import os4 from "node:os";
+import { randomBytes as randomBytes2 } from "node:crypto";
+var MIN_AGENT_VERSION = "1.1.0";
+var KEY_RE = /^dbk_[a-z0-9]{40}$/;
+var ENV_FIX = "Or set DATABULL_URL and DATABULL_API_KEY (create a key in your dashboard under Settings \u2192 API keys).";
+var cleanUrl = (u2) => String(u2).trim().replace(/\/+$/, "").replace(/\/mcp$/, "");
+function endpoint(url) {
+  const mock = process.env.DATABULL_TEST_HEALTH_URL;
+  return mock ? `${mock}/mcp?host=${encodeURIComponent(new URL(url).host)}` : `${url}/mcp`;
+}
+async function rpc(conn, method, params = {}, { timeoutMs = 45e3 } = {}) {
+  let res;
+  try {
+    res = await fetchWithTimeout(endpoint(conn.url), {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream", Authorization: `Bearer ${conn.key}`, "User-Agent": "databull-cli" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
+    }, timeoutMs);
+  } catch {
+    throw new Fail(`Couldn't reach ${conn.url}.`, { fix: "Check the address and your internet connection, then try again." });
+  }
+  const type = res.headers.get("content-type") || "";
+  if (res.status === 401) {
+    const body2 = await res.json().catch(() => null);
+    throw new Fail(body2?.error?.message || "The API key was refused.", {
+      fix: conn.install ? "Run the command again to create a new key for this computer." : "Check that DATABULL_API_KEY belongs to this address, or create a new key under Settings \u2192 API keys.",
+      code: "unauthorized"
+    });
+  }
+  if (!type.includes("application/json")) {
+    const health = await fetchHealth(conn.url);
+    if (!health) throw new Fail(`${conn.url} isn't a DataBull install.`, { fix: "Check the address: it's the one you open your dashboard at." });
+    throw new Fail(`${conn.url} runs DataBull ${health.version}; the API needs ${MIN_AGENT_VERSION} or newer.`, { fix: "Update it with `npx databull@latest update`, then try again.", code: "too_old" });
+  }
+  const body = await res.json().catch(() => null);
+  if (!body) throw new Fail(`${conn.url} sent an answer the CLI couldn't read.`, { fix: "Try again in a moment." });
+  if (body.error) throw new Fail(body.error.message || "The request failed.");
+  return body.result;
+}
+async function callTool(conn, name, args = {}) {
+  const r2 = await rpc(conn, "tools/call", { name, arguments: args });
+  if (r2?.isError) throw new Fail(r2.content?.[0]?.text || `${name} failed.`);
+  if (r2?.structuredContent) return r2.structuredContent;
+  try {
+    return JSON.parse(r2.content[0].text);
+  } catch {
+    throw new Fail(`${name} answered in a shape the CLI doesn't understand.`, { fix: "Update the CLI: `npx databull@latest`." });
+  }
+}
+function newApiKey() {
+  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let s = "";
+  while (s.length < 40) for (const b3 of randomBytes2(64)) if (b3 < 252 && s.length < 40) s += alphabet[b3 % 36];
+  return `dbk_${s}`;
+}
+var sqlText = (s) => `'${String(s).replace(/[^\w .@()+#:/-]/g, "").slice(0, 60).replace(/'/g, "''")}'`;
+var hostName = () => os4.hostname().replace(/\.local$/, "").slice(0, 30) || "this computer";
+async function ensureAgentVersion(ctx, install, runUpdate2) {
+  const health = await fetchHealth(install.url);
+  if (!health) throw new Fail(`${install.url} isn't answering.`, { fix: "Check it with `npx databull@latest status`." });
+  if (compareVersions(health.version, MIN_AGENT_VERSION) >= 0) return health.version;
+  const why = `${install.name} runs DataBull ${health.version}; API keys and AI agents need ${MIN_AGENT_VERSION} or newer.`;
+  if (!ctx.flags.yes) {
+    if (!canPrompt()) throw new Fail(why, { fix: "Update it with `npx databull@latest update` (or pass --yes to update now)." });
+    warn(why);
+    if (!await askConfirm({ message: `Update ${install.name} now? Your data stays as it is.` })) throw new Cancelled();
+  } else {
+    info(`${why} Updating it first.`);
+  }
+  const before = ctx.flags.name;
+  ctx.flags.name = install.name;
+  try {
+    await runUpdate2(ctx);
+  } finally {
+    ctx.flags.name = before;
+  }
+  const after = await fetchHealth(install.url);
+  if (!after || compareVersions(after.version, MIN_AGENT_VERSION) < 0) throw new Fail(`${install.name} still isn't on ${MIN_AGENT_VERSION}.`, { fix: "Run `npx databull@latest update` and try again." });
+  return after.version;
+}
+async function createKeyOnInstall(ctx, install, { label, pii = false, connect: connect2 }) {
+  await connect2(ctx, null, null, { accountId: install.account_id });
+  const key = newApiKey();
+  const sql = `INSERT INTO api_keys (user_id, name, prefix, hash, pii, created_at) SELECT id, ${sqlText(label)}, '${key.slice(0, 12)}', '${sha256hex(key)}', ${pii ? 1 : 0}, ${Date.now()} FROM users ORDER BY id LIMIT 1;`;
+  const configFile = ensureD1Config(ctx.paths.installDir(install.name), install);
+  const r2 = await withStep(null, null, "Creating an API key", async () => {
+    const res = await d1Execute(ctx, install, configFile, sql, "create API key");
+    return { value: res, label: res.changes === 0 ? "No login yet" : "API key created", detail: res.changes === 0 ? "" : label };
+  });
+  if (r2.value.changes === 0) throw new Fail(`${install.name} has no login yet, so there's no account to give a key to.`, { fix: "Create your login first (`npx databull@latest status` shows the setup link), then try again." });
+  return { key, prefix: key.slice(0, 12), label };
+}
+async function resolveConnection(ctx, { pickInstall: pickInstall2, connect: connect2, runUpdate: runUpdate2, save: save2 }) {
+  const url = ctx.flags.url || process.env.DATABULL_URL;
+  const key = ctx.flags.apiKey || process.env.DATABULL_API_KEY;
+  if (url || key) {
+    if (!url || !key) throw new Fail("Pass both the address and the API key.", { fix: "Set DATABULL_URL=https://\u2026 and DATABULL_API_KEY=dbk_\u2026 (or use --url and --api-key)." });
+    if (!KEY_RE.test(key)) throw new Fail("That isn't a DataBull API key (they start with dbk_ and have 44 characters).", { fix: "Copy it again from Settings \u2192 API keys." });
+    if (!/^https?:\/\//.test(url)) throw new Fail(`"${url}" isn't an address.`, { fix: "Use the full address, e.g. https://analytics.example.com." });
+    return { url: cleanUrl(url), key };
+  }
+  const install = await pickInstall2(ctx, { verb: "read" });
+  if (!install) throw new Fail("No DataBull install on this computer.", { fix: `Install it with \`npx databull@latest\`. ${ENV_FIX}` });
+  if (install.api_key && KEY_RE.test(install.api_key)) return { url: install.url, key: install.api_key, install };
+  await ensureAgentVersion(ctx, install, runUpdate2);
+  if (!ctx.flags.yes) {
+    if (!canPrompt()) throw new Fail(`This computer has no API key for ${install.name} yet.`, { fix: "Run the command in a terminal to create one, pass --yes, or create it with `npx databull@latest api-key create`." });
+    info(`To read your stats, this computer needs an API key for ${install.name} (read-only).`);
+    if (!await askConfirm({ message: "Create one now? It uses your Cloudflare login." })) throw new Cancelled();
+  }
+  const made = await createKeyOnInstall(ctx, install, { label: `CLI on ${hostName()}`, connect: connect2 });
+  upsertInstall(ctx.cfg, { ...install, api_key: made.key });
+  save2(ctx);
+  return { url: install.url, key: made.key, install: { ...install, api_key: made.key } };
+}
+
+// src/commands/data.mjs
+var out2 = (s = "") => process.stdout.write(`${s}
+`);
+var strip = (s) => String(s).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+function money(n, currency) {
+  if (n === null || n === void 0) return import_picocolors3.default.dim("\u2013");
+  const big = Math.abs(n) >= 1e3;
+  try {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency, maximumFractionDigits: big ? 0 : 2, minimumFractionDigits: big || Number.isInteger(n) ? 0 : 2 }).format(n);
+  } catch {
+    return `${n} ${currency}`;
+  }
+}
+var num = (n) => n === null || n === void 0 ? import_picocolors3.default.dim("\u2013") : Number(n).toLocaleString("en-US");
+var pctText = (n) => n === null || n === void 0 ? "" : `${n}%`;
+function change(n) {
+  if (n === null || n === void 0) return import_picocolors3.default.dim("new");
+  if (n === 0) return import_picocolors3.default.dim("\xB10%");
+  return n > 0 ? import_picocolors3.default.green(`+${n}%`) : import_picocolors3.default.red(`${n}%`);
+}
+function duration(s) {
+  if (!s) return "0s";
+  const m2 = Math.floor(s / 60);
+  return m2 ? `${m2}m ${Math.round(s % 60)}s` : `${Math.round(s)}s`;
+}
+function ago(iso) {
+  if (!iso) return "";
+  const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1e3);
+  if (s < 60) return "just now";
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  if (s < 30 * 86400) return `${Math.floor(s / 86400)}d ago`;
+  return iso.slice(0, 10);
+}
+function bar(value, max, width = 14) {
+  if (!max || !value) return " ".repeat(width);
+  const eighths = Math.max(1, Math.round(value / max * width * 8));
+  const full = Math.floor(eighths / 8);
+  const part = ["", "\u258F", "\u258E", "\u258D", "\u258C", "\u258B", "\u258A", "\u2589"][eighths % 8];
+  return ("\u2588".repeat(full) + part).padEnd(width, " ").slice(0, width);
+}
+function spark(values) {
+  const max = Math.max(...values, 0);
+  if (!max) return import_picocolors3.default.dim("\u2581".repeat(values.length));
+  return values.map((v2) => "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588"[Math.min(7, Math.round(v2 / max * 7))]).join("");
+}
+var short = (s, n = 34) => s && s.length > n ? `${s.slice(0, n - 1)}\u2026` : s || "";
+var regions = (() => {
+  try {
+    return new Intl.DisplayNames(["en"], { type: "region" });
+  } catch {
+    return null;
+  }
+})();
+var countryName = (code) => {
+  if (!code || !/^[A-Z]{2}$/.test(code)) return code;
+  try {
+    return `${regions.of(code)} (${code})`;
+  } catch {
+    return code;
+  }
+};
+function rowName(x2, dim, n = 44) {
+  if (x2.label) return import_picocolors3.default.italic(short(x2.label[0].toUpperCase() + x2.label.slice(1), n));
+  return short(dim === "country" ? countryName(x2.name) : x2.name, n);
+}
+function table(rows, cols) {
+  const cells = rows.map((r2) => cols.map((c) => String(c.get(r2) ?? "")));
+  const widths = cols.map((c, i) => Math.max(strip(c.label).length, ...cells.map((row) => strip(row[i]).length)));
+  const pad = (s, i) => cols[i].right ? " ".repeat(widths[i] - strip(s).length) + s : s + " ".repeat(widths[i] - strip(s).length);
+  out2(`  ${cols.map((c, i) => import_picocolors3.default.dim(pad(c.label, i))).join("  ")}`);
+  for (const row of cells) out2(`  ${row.map((s, i) => pad(s, i)).join("  ")}`);
+}
+function header(r2, title) {
+  const range2 = r2.range ? import_picocolors3.default.dim(`  ${r2.range.from === r2.range.to ? r2.range.from : `${r2.range.from} \u2192 ${r2.range.to}`}${r2.range.period && r2.range.period !== "custom" ? ` (${r2.range.period})` : ""}`) : "";
+  out2("");
+  out2(`${import_picocolors3.default.bold(title || r2.site?.domain || "")}${range2}`);
+  out2("");
+}
+function filters(ctx) {
+  const f = {};
+  for (const item of ctx.flags.filter || []) {
+    const i = item.indexOf("=");
+    if (i < 1) throw new Fail(`--filter needs key=value (got "${item}").`, { fix: "Example: --filter referrer=news.ycombinator.com --filter country=US" });
+    f[item.slice(0, i).trim()] = item.slice(i + 1).trim();
+  }
+  return Object.keys(f).length ? f : void 0;
+}
+function range(ctx) {
+  const r2 = {};
+  if (ctx.flags.period) r2.period = ctx.flags.period;
+  if (ctx.flags.from) r2.from = ctx.flags.from;
+  if (ctx.flags.to) r2.to = ctx.flags.to;
+  const f = filters(ctx);
+  if (f) r2.filters = f;
+  return r2;
+}
+function limit(ctx, def) {
+  if (ctx.flags.limit === void 0) return def;
+  const n = Number(ctx.flags.limit);
+  if (!Number.isInteger(n) || n < 1) throw new Fail(`--limit must be a whole number (got "${ctx.flags.limit}").`);
+  return n;
+}
+var siteArg = (ctx, i = 0) => ctx.flags.site || ctx.args[i];
+function renderSites(r2) {
+  out2("");
+  if (!r2.sites.length) return out2("  No sites yet. Add one in your dashboard.");
+  table(r2.sites, [
+    { label: "Site", get: (s) => import_picocolors3.default.bold(s.domain) },
+    { label: "Today", get: (s) => num(s.visitors_today), right: true },
+    { label: "Online", get: (s) => s.online_now ? import_picocolors3.default.green(`\u25CF ${s.online_now}`) : import_picocolors3.default.dim("0"), right: true },
+    { label: "7d visitors", get: (s) => `${num(s.last_7_days.visitors)} ${change(pctChange(s.last_7_days.visitors, s.last_7_days.previous.visitors))}`, right: true },
+    { label: "7d revenue", get: (s) => `${money(s.last_7_days.revenue, r2.currency)} ${change(pctChange(s.last_7_days.revenue, s.last_7_days.previous.revenue))}`, right: true },
+    { label: "30d revenue", get: (s) => money(s.last_30_days.revenue, r2.currency), right: true },
+    { label: "Id", get: (s) => import_picocolors3.default.dim(s.id) }
+  ]);
+  out2("");
+}
+var pctChange = (cur, prev) => prev ? Math.round((cur - prev) / prev * 1e3) / 10 : cur ? null : 0;
+function renderOverview(r2) {
+  header(r2);
+  const t = r2.totals;
+  const c = r2.change_pct;
+  const rows = [
+    ["Visitors", num(t.visitors), change(c.visitors)],
+    ["Revenue", money(t.revenue, r2.currency), change(c.revenue)],
+    ["Sales", num(t.sales), change(c.sales)],
+    ["Conversion", pctText(t.conversion_rate_pct), change(c.conversion_rate_pct)],
+    ["Revenue/visitor", money(t.revenue_per_visitor, r2.currency), change(c.revenue_per_visitor)],
+    ["Pageviews", num(t.pageviews), change(c.pageviews)],
+    ["Bounce rate", pctText(t.bounce_rate_pct), ""],
+    ["Visit length", duration(t.avg_visit_seconds), ""]
+  ];
+  if (t.refunds) rows.push(["Refunds", money(t.refunds, r2.currency), ""]);
+  for (const [k3, v2, d3] of rows) out2(`  ${import_picocolors3.default.dim(k3.padEnd(16))}${v2.padStart(strip(v2).length > 12 ? strip(v2).length : 12 + (v2.length - strip(v2).length))}  ${d3}`);
+  out2(`  ${import_picocolors3.default.dim("Online now".padEnd(16))}${String(r2.online_now).padStart(12)}  ${r2.online_now ? import_picocolors3.default.green("\u25CF") : ""}`);
+  if (r2.series?.length > 1) {
+    out2("");
+    out2(`  ${import_picocolors3.default.dim("Visitors".padEnd(16))}${import_picocolors3.default.blue(spark(r2.series.map((b3) => b3.visitors)))}`);
+    out2(`  ${import_picocolors3.default.dim("Revenue".padEnd(16))}${import_picocolors3.default.magenta(spark(r2.series.map((b3) => b3.revenue || 0)))}`);
+    out2(`  ${import_picocolors3.default.dim("".padEnd(16))}${import_picocolors3.default.dim(`${r2.series[0].date} \u2026 ${r2.series[r2.series.length - 1].date} (${r2.granularity})`)}`);
+  }
+  if (r2.spikes?.length) {
+    out2("");
+    for (const s of r2.spikes) out2(`  ${import_picocolors3.default.yellow("\u25B2")} ${s.date}: ${import_picocolors3.default.bold(s.source)} sent ${s.times_usual}\xD7 its usual traffic (${num(s.visitors)} visitors)`);
+  }
+  out2("");
+}
+function renderBreakdown(r2) {
+  header(r2, `${r2.site.domain} \xB7 ${r2.dimension.replace(/_/g, " ")}`);
+  if (!r2.rows.length) return out2(`  Nothing for this period.
+`);
+  const byRevenue = r2.sorted_by === "revenue";
+  const max = Math.max(...r2.rows.map((x2) => byRevenue ? x2.revenue || 0 : x2.visitors || x2.completions || 0));
+  const hasMoney = r2.rows.some((x2) => x2.revenue !== void 0);
+  const cols = [
+    { label: "#", get: (x2) => import_picocolors3.default.dim(String(r2.rows.indexOf(x2) + 1)), right: true },
+    { label: r2.dimension.replace(/_/g, " "), get: (x2) => rowName(x2, r2.dimension) + (x2.country ? import_picocolors3.default.dim(` ${x2.country}`) : "") },
+    { label: "", get: (x2) => (byRevenue ? import_picocolors3.default.magenta : import_picocolors3.default.blue)(bar(byRevenue ? x2.revenue || 0 : x2.visitors || x2.completions || 0, max)) },
+    { label: "Visitors", get: (x2) => num(x2.visitors), right: true }
+  ];
+  if (r2.rows.some((x2) => x2.pageviews !== void 0)) cols.push({ label: "Pageviews", get: (x2) => num(x2.pageviews), right: true });
+  if (r2.rows.some((x2) => x2.completions !== void 0)) cols.push({ label: "Completions", get: (x2) => num(x2.completions), right: true });
+  if (hasMoney) {
+    cols.push({ label: "Revenue", get: (x2) => x2.revenue ? money(x2.revenue, r2.currency) : import_picocolors3.default.dim("\u2013"), right: true });
+    if (r2.rows.some((x2) => x2.sales !== void 0)) cols.push({ label: "Sales", get: (x2) => x2.sales ? num(x2.sales) : import_picocolors3.default.dim("\u2013"), right: true });
+  }
+  if (r2.rows.some((x2) => x2.conversion_rate_pct !== void 0)) cols.push({ label: "Conv.", get: (x2) => pctText(x2.conversion_rate_pct), right: true });
+  table(r2.rows, cols);
+  out2("");
+  out2(import_picocolors3.default.dim(`  ${num(r2.total_visitors)} visitors in total \xB7 showing ${r2.rows.length} of ${r2.rows_total} \xB7 sorted by ${r2.sorted_by}`));
+  out2("");
+}
+function renderCompare(r2) {
+  out2("");
+  out2(`${import_picocolors3.default.bold(r2.site.domain)}  ${r2.range.from} \u2192 ${r2.range.to} ${import_picocolors3.default.dim(`vs ${r2.previous_range.from} \u2192 ${r2.previous_range.to}`)}`);
+  out2("");
+  const t = r2.totals;
+  const p2 = r2.previous_period;
+  const row = (k3, a, b3, d3) => out2(`  ${import_picocolors3.default.dim(k3.padEnd(16))}${a.padStart(12 + (a.length - strip(a).length))}  ${import_picocolors3.default.dim("vs")} ${b3.padEnd(10 + (b3.length - strip(b3).length))}  ${d3}`);
+  row("Visitors", num(t.visitors), num(p2.visitors), change(r2.change_pct.visitors));
+  row("Revenue", money(t.revenue, r2.currency), money(p2.revenue, r2.currency), change(r2.change_pct.revenue));
+  row("Sales", num(t.sales), num(p2.sales), change(r2.change_pct.sales));
+  row("Conversion", pctText(t.conversion_rate_pct), pctText(p2.conversion_rate_pct), change(r2.change_pct.conversion_rate_pct));
+  const list = (title, items, field) => {
+    if (!items.length) return;
+    out2("");
+    out2(`  ${import_picocolors3.default.bold(title)}`);
+    for (const m2 of items) {
+      const delta = field === "revenue" ? money(Math.abs(m2.change), r2.currency) : num(Math.abs(m2.change));
+      out2(`  ${m2.change > 0 ? import_picocolors3.default.green(`\u25B2 +${delta}`) : import_picocolors3.default.red(`\u25BC -${delta}`)}  ${rowName(m2, r2.dimension, 40)}${m2.country ? import_picocolors3.default.dim(` ${m2.country}`) : ""} ${import_picocolors3.default.dim(`(${field === "revenue" ? `${money(m2.previous_revenue, r2.currency)} \u2192 ${money(m2.revenue, r2.currency)}` : `${num(m2.previous_visitors)} \u2192 ${num(m2.visitors)}`})`)}`);
+    }
+  };
+  const dim = r2.dimension.replace(/_/g, " ");
+  list(`Revenue up, by ${dim}`, r2.gainers_by_revenue, "revenue");
+  list(`Revenue down, by ${dim}`, r2.losers_by_revenue, "revenue");
+  list(`Visitors up, by ${dim}`, r2.gainers_by_visitors, "visitors");
+  list(`Visitors down, by ${dim}`, r2.losers_by_visitors, "visitors");
+  out2("");
+}
+function sourceText(s) {
+  if (!s) return import_picocolors3.default.dim("not matched to a visit");
+  return [s.referrer || s.channel, s.utm_campaign ? import_picocolors3.default.dim(`campaign ${s.utm_campaign}`) : "", s.country ? import_picocolors3.default.dim(s.country) : ""].filter(Boolean).join(" \xB7 ");
+}
+function renderSales(r2) {
+  header(r2);
+  if (!r2.sales.length) return out2("  No sales in this period.\n");
+  table(r2.sales, [
+    { label: "When", get: (s) => import_picocolors3.default.dim(ago(s.at)) },
+    { label: "Amount", get: (s) => s.refunded ? `${money(s.amount, r2.currency)} ${import_picocolors3.default.red(`-${money(s.refunded, r2.currency)}`)}` : money(s.amount, r2.currency), right: true },
+    { label: "Product", get: (s) => short(s.product, 26) },
+    { label: "Type", get: (s) => import_picocolors3.default.dim((s.charge_type || "").replace("_", "-")) },
+    { label: "Source", get: (s) => sourceText(s.source) },
+    ...r2.sales.some((s) => s.customer) ? [{ label: "Customer", get: (s) => s.customer?.email || "" }] : [],
+    { label: "Visitor", get: (s) => import_picocolors3.default.dim((s.visitor_id || "").slice(0, 10)) }
+  ]);
+  out2("");
+  const total = r2.by_product.reduce((a, p2) => a + p2.revenue, 0);
+  out2(import_picocolors3.default.dim(`  ${money(total, r2.currency)} from ${r2.by_product.reduce((a, p2) => a + p2.sales, 0)} sales${r2.by_product.length > 1 ? ` across ${r2.by_product.length} products` : ""}${r2.has_more ? " \xB7 more with --limit" : ""} \xB7 see a buyer's path: databull visitor <visitor id>`));
+  out2("");
+}
+function renderVisitors(r2) {
+  header(r2);
+  if (!r2.visitors.length) return out2("  No visitors match.\n");
+  table(r2.visitors, [
+    { label: "Last seen", get: (v2) => import_picocolors3.default.dim(ago(v2.last_seen)) },
+    { label: "Visitor", get: (v2) => v2.email || v2.name ? `${v2.name || v2.email}` : import_picocolors3.default.dim(v2.visitor_id.slice(0, 10)) },
+    { label: "From", get: (v2) => short(v2.source?.referrer || v2.source?.channel || "", 24) },
+    { label: "Path", get: (v2) => short((v2.path || []).join(" \u2192 "), 40) },
+    { label: "Visits", get: (v2) => num(v2.visits_in_range), right: true },
+    { label: "Time", get: (v2) => duration(v2.time_on_site_seconds), right: true },
+    { label: "Revenue", get: (v2) => v2.revenue ? import_picocolors3.default.magenta(money(v2.revenue, r2.currency)) : import_picocolors3.default.dim("\u2013"), right: true },
+    { label: "Where", get: (v2) => import_picocolors3.default.dim(short(v2.location || "", 24)) }
+  ]);
+  out2("");
+  out2(import_picocolors3.default.dim(`  ${num(r2.total_visitors)} visitors \xB7 ${num(r2.paying_visitors)} paid${r2.has_more ? " \xB7 more with --page 1" : ""}`));
+  out2("");
+}
+function renderVisitor(r2) {
+  const v2 = r2.visitor;
+  out2("");
+  out2(`${import_picocolors3.default.bold(v2.name || v2.email || v2.visitor_id)}  ${import_picocolors3.default.dim([r2.site.domain, `first seen ${ago(v2.first_seen)}`, `${v2.visits} visit${v2.visits === 1 ? "" : "s"}`, v2.location, v2.device].filter(Boolean).join(" \xB7 "))}`);
+  out2("");
+  if (r2.payments.length) {
+    for (const p2 of r2.payments) out2(`  ${import_picocolors3.default.magenta("$")} ${import_picocolors3.default.bold(money(p2.amount, r2.currency))} ${p2.product || ""} ${import_picocolors3.default.dim(`${ago(p2.at)} \xB7 credited to ${sourceText(p2.source)}`)}`);
+    out2("");
+  }
+  const events = [...r2.events].reverse();
+  for (const s of [...r2.visits].reverse()) {
+    out2(`  ${import_picocolors3.default.blue("\u25CF")} ${import_picocolors3.default.dim(s.started?.slice(0, 16).replace("T", " "))}  ${import_picocolors3.default.bold(s.referrer || s.channel)}${s.campaign ? import_picocolors3.default.dim(` \xB7 ${s.campaign}`) : ""}  ${import_picocolors3.default.dim(`${s.pageviews} page${s.pageviews === 1 ? "" : "s"} \xB7 ${duration(s.seconds)}`)}`);
+    const inVisit = events.filter((e2) => e2.visit_id === s.visit_id);
+    for (const e2 of inVisit.slice(0, 15)) out2(`      ${e2.type === "pageview" ? import_picocolors3.default.dim("\u2192") : import_picocolors3.default.yellow("\u2605")} ${e2.type === "pageview" ? e2.page : `${e2.type}: ${e2.name || ""}`}`);
+  }
+  out2("");
+}
+function renderLive(r2) {
+  out2("");
+  out2(`${import_picocolors3.default.bold(r2.site.domain)}  ${r2.online_now ? import_picocolors3.default.green(`\u25CF ${r2.online_now} online now`) : import_picocolors3.default.dim("nobody online right now")}`);
+  out2("");
+  if (r2.visitors.length) {
+    table(r2.visitors.slice(0, 20), [
+      { label: "Page", get: (v2) => short(v2.page, 36) },
+      { label: "From", get: (v2) => short(v2.referrer || v2.channel || "", 26) },
+      { label: "Where", get: (v2) => import_picocolors3.default.dim(short(v2.location || "", 22)) },
+      { label: "Device", get: (v2) => import_picocolors3.default.dim(short(v2.device || "", 26)) }
+    ]);
+    out2("");
+  }
+  if (r2.recent_sales.length) {
+    for (const s of r2.recent_sales) out2(`  ${import_picocolors3.default.magenta("$")} ${money(s.amount, s.currency)} ${s.product || ""} ${import_picocolors3.default.dim(`${ago(s.at)} \xB7 ${s.referrer || "direct"}${s.country ? ` \xB7 ${s.country}` : ""}`)}`);
+    out2("");
+  }
+}
+function renderGoals(r2) {
+  header(r2, `${r2.site.domain} \xB7 goals`);
+  if (!r2.goals.length) return out2("  No goals completed in this period. Track one with data-fast-goal or datacheap('goal').\n");
+  const max = Math.max(...r2.goals.map((g) => g.completions));
+  table(r2.goals, [
+    { label: "Goal", get: (g) => import_picocolors3.default.bold(g.goal) },
+    { label: "", get: (g) => import_picocolors3.default.yellow(bar(g.completions, max)) },
+    { label: "Completions", get: (g) => num(g.completions), right: true },
+    { label: "Visitors", get: (g) => num(g.visitors), right: true },
+    { label: "Conv.", get: (g) => pctText(g.conversion_rate_pct), right: true },
+    { label: "Revenue", get: (g) => g.revenue ? money(g.revenue, r2.currency) : import_picocolors3.default.dim("\u2013"), right: true }
+  ]);
+  out2("");
+}
+function renderFunnels(r2) {
+  header(r2, `${r2.site.domain} \xB7 funnels`);
+  if (!r2.funnels.length) return out2("  No funnels yet. Create one in the dashboard under Funnels.\n");
+  for (const f of r2.funnels) {
+    out2(`  ${import_picocolors3.default.bold(f.name)}  ${import_picocolors3.default.dim(`${f.overall_conversion_pct}% make it to the end`)}`);
+    const max = Math.max(...f.steps.map((s) => s.visitors), 1);
+    f.steps.forEach((s, i) => {
+      out2(`  ${import_picocolors3.default.dim(`${i + 1}.`)} ${short(s.step, 30).padEnd(30)} ${import_picocolors3.default.blue(bar(s.visitors, max, 20))} ${num(s.visitors).padStart(7)}  ${i ? import_picocolors3.default.dim(`${s.from_previous_pct}% of previous`) : ""}${s.revenue ? `  ${money(s.revenue, r2.currency)}` : ""}`);
+    });
+    out2("");
+  }
+  if (r2.note) out2(import_picocolors3.default.dim(`  ${r2.note}
+`));
+}
+function renderLtv(r2) {
+  header(r2, `${r2.site.domain} \xB7 customer value by ${r2.dimension.replace(/_/g, " ")}`);
+  if (!r2.by_source.length) return out2("  No customers whose first payment falls in this period.\n");
+  table(r2.by_source, [
+    { label: "Source", get: (g) => rowName({ name: g.source, label: g.label }, r2.dimension, 34) },
+    { label: "Customers", get: (g) => num(g.customers), right: true },
+    { label: "Revenue", get: (g) => money(g.revenue, r2.currency), right: true },
+    { label: "Avg value", get: (g) => money(g.average_value, r2.currency), right: true },
+    { label: "Recurring", get: (g) => pctText(g.recurring_share_pct), right: true },
+    { label: "Repeat", get: (g) => pctText(g.repeat_rate_pct), right: true }
+  ]);
+  out2("");
+  out2(import_picocolors3.default.dim(`  ${num(r2.totals.customers)} customers \xB7 ${money(r2.totals.revenue, r2.currency)} \xB7 ${money(r2.totals.average_value, r2.currency)} each on average`));
+  out2("");
+}
+var COMMANDS2 = {
+  sites: { tool: "list_sites", input: () => ({}), render: renderSites },
+  stats: { tool: "get_overview", input: (ctx) => ({ site: siteArg(ctx), ...range(ctx) }), render: renderOverview },
+  sources: {
+    tool: "get_breakdown",
+    input: (ctx) => ({ site: siteArg(ctx), dimension: ctx.flags.dim || "referrer", sort: ctx.flags.by || "revenue", limit: limit(ctx, 15), ...range(ctx) }),
+    render: renderBreakdown
+  },
+  breakdown: {
+    tool: "get_breakdown",
+    input: (ctx) => {
+      const dimension = ctx.flags.dim || ctx.args[0];
+      if (!dimension) throw new Fail("Which dimension? e.g. `databull breakdown country`.", { fix: "Dimensions: channel, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content, country, region, city, browser, os, device, entry_page, exit_page, hostname, page, goal, outbound." });
+      return { site: ctx.flags.site || ctx.args[ctx.flags.dim ? 0 : 1], dimension, sort: ctx.flags.by || ctx.flags.sort || "visitors", limit: limit(ctx, 15), ...range(ctx) };
+    },
+    render: renderBreakdown
+  },
+  compare: { tool: "compare_periods", input: (ctx) => ({ site: siteArg(ctx), ...ctx.flags.dim || ctx.flags.by ? { dimension: ctx.flags.dim || ctx.flags.by } : {}, ...ctx.flags.limit ? { limit: limit(ctx, 5) } : {}, ...range(ctx), period: ctx.flags.period || (ctx.flags.from ? void 0 : "7d") }), render: renderCompare },
+  sales: { tool: "list_sales", input: (ctx) => ({ site: siteArg(ctx), limit: limit(ctx, 20), ...ctx.flags.page ? { page: Number(ctx.flags.page) } : {}, ...range(ctx) }), render: renderSales },
+  visitors: {
+    tool: "list_visitors",
+    input: (ctx) => ({ site: siteArg(ctx), sort: ctx.flags.sort || ctx.flags.by || "recent", ...ctx.flags.customers ? { customers_only: true } : {}, limit: limit(ctx, 20), ...ctx.flags.page ? { page: Number(ctx.flags.page) } : {}, ...range(ctx) }),
+    render: renderVisitors
+  },
+  visitor: {
+    tool: "get_visitor",
+    input: (ctx) => {
+      if (!ctx.args[0]) throw new Fail("Which visitor? e.g. `databull visitor 3f2a\u2026`", { fix: "Visitor ids are in `databull sales` and `databull visitors`." });
+      return { site: ctx.flags.site || ctx.args[1], visitor_id: ctx.args[0] };
+    },
+    render: renderVisitor
+  },
+  live: { tool: "get_realtime", input: (ctx) => ({ site: siteArg(ctx) }), render: renderLive },
+  goals: { tool: "get_goals", input: (ctx) => ({ site: siteArg(ctx), ...range(ctx) }), render: renderGoals },
+  funnels: { tool: "get_funnels", input: (ctx) => ({ site: siteArg(ctx), ...ctx.flags.funnel ? { funnel: ctx.flags.funnel } : {}, ...range(ctx) }), render: renderFunnels },
+  ltv: { tool: "get_customer_value", input: (ctx) => ({ site: siteArg(ctx), ...ctx.flags.dim || ctx.flags.by ? { dimension: ctx.flags.dim || ctx.flags.by } : {}, ...range(ctx) }), render: renderLtv }
+};
+async function withKey(ctx, deps, tool, input) {
+  const conn = await resolveConnection(ctx, deps);
+  try {
+    return await callTool(conn, tool, input);
+  } catch (err) {
+    if (err.code !== "unauthorized" || !conn.install?.api_key) throw err;
+    forgetInstallFields(ctx.cfg, conn.install, ["api_key"]);
+    deps.save(ctx);
+    process.stderr.write(`${import_picocolors3.default.yellow("\u25B2")} The API key saved on this computer no longer works (revoked?). Getting a new one.
+`);
+    return callTool(await resolveConnection(ctx, deps), tool, input);
+  }
+}
+async function runData(ctx, deps) {
+  if (ctx.command === "query") {
+    const [tool, json2] = ctx.args;
+    if (!tool) throw new Fail('Which tool? e.g. `databull query get_overview \'{"period":"7d"}\'`.', { fix: "Tools: list_sites, get_overview, get_breakdown, compare_periods, list_sales, list_visitors, get_visitor, get_realtime, get_goals, get_funnels, get_customer_value." });
+    let args = {};
+    if (json2) {
+      try {
+        args = JSON.parse(json2);
+      } catch {
+        throw new Fail("The tool's arguments must be JSON.", { fix: `Example: '{"site":"example.com","period":"7d"}'` });
+      }
+    }
+    process.stdout.write(`${JSON.stringify(await withKey(ctx, deps, tool, args), null, 2)}
+`);
+    return;
+  }
+  const cmd = COMMANDS2[ctx.command];
+  const input = cmd.input(ctx);
+  for (const k3 of Object.keys(input)) if (input[k3] === void 0) delete input[k3];
+  const result = await withKey(ctx, deps, cmd.tool, input);
+  if (ctx.flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  else cmd.render(result);
+}
+
+// src/commands/keys.mjs
+var fmtDate = (ms) => ms ? new Date(Number(ms)).toISOString().slice(0, 16).replace("T", " ") : "\u2013";
+async function runApiKey(ctx, { pickInstall: pickInstall2, connect: connect2, runUpdate: runUpdate2, save: save2 }) {
+  const sub = ctx.args[0] || "list";
+  if (!["create", "list", "revoke"].includes(sub)) throw new Fail(`Unknown api-key command "${sub}".`, { fix: `Use \`${CMD} api-key create\`, \`list\` or \`revoke <prefix>\`.` });
+  const install = await pickInstall2(ctx, { verb: "manage API keys for" });
+  if (!install) throw new Fail("No DataBull install on this computer.", { fix: `Manage keys in your dashboard under Settings \u2192 API keys, or install with \`${CMD}\`.` });
+  await ensureAgentVersion(ctx, install, runUpdate2);
+  if (sub === "create") {
+    const label = (ctx.flags.label || `API key ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`).trim();
+    const made = await createKeyOnInstall(ctx, install, { label, pii: !!ctx.flags.pii, connect: connect2 });
+    box("Your API key (shown once)", [
+      import_picocolors3.default.bold(made.key),
+      "",
+      `${import_picocolors3.default.dim("Address")}  ${install.url}`,
+      `${import_picocolors3.default.dim("Access ")}  read-only${ctx.flags.pii ? ", including customer names and emails" : ", customer details hidden"}`,
+      "",
+      import_picocolors3.default.dim("Use it anywhere:"),
+      `  DATABULL_URL=${install.url} DATABULL_API_KEY=${made.key.slice(0, 8)}\u2026 ${CMD} stats`,
+      import_picocolors3.default.dim(`AI agents: \`${CMD} mcp\` sets them up for you.`)
+    ], { color: import_picocolors3.default.green });
+    end(`Store it somewhere safe. Revoke it any time with \`${CMD} api-key revoke ${made.prefix}\`.`);
+    return;
+  }
+  await connect2(ctx, null, null, { accountId: install.account_id });
+  const configFile = ensureD1Config(ctx.paths.installDir(install.name), install);
+  if (sub === "list") {
+    const r3 = await d1Execute(ctx, install, configFile, "SELECT id, name, prefix, pii, created_at, last_used_at FROM api_keys WHERE revoked_at IS NULL ORDER BY created_at DESC;", "list API keys");
+    if (!r3.results.length) {
+      end(`No API keys yet. Create one with \`${CMD} api-key create\` (or \`${CMD} mcp\` for AI agents).`);
+      return;
+    }
+    box(`API keys on ${install.name}`, r3.results.map((k3) => `${import_picocolors3.default.bold(k3.prefix)}\u2026  ${String(k3.name).padEnd(28)} ${import_picocolors3.default.dim(`created ${fmtDate(k3.created_at)} \xB7 last used ${fmtDate(k3.last_used_at)}${k3.pii ? " \xB7 customer details" : ""}`)}`));
+    end(`Revoke one with \`${CMD} api-key revoke <prefix>\`.`);
+    return;
+  }
+  const which = ctx.args[1];
+  if (!which) throw new Fail("Which key? Pass its prefix, e.g. `api-key revoke dbk_ab12cd34`.", { fix: `\`${CMD} api-key list\` shows them.` });
+  const prefix = which.replace(/…$/, "").slice(0, 12);
+  if (!/^dbk_[a-z0-9]{8}$/.test(prefix) && !/^\d+$/.test(which)) throw new Fail(`"${which}" isn't a key prefix (dbk_ + 8 characters) or id.`, { fix: `\`${CMD} api-key list\` shows them.` });
+  const where = /^\d+$/.test(which) ? `id = ${Number(which)}` : `prefix = '${prefix}'`;
+  const r2 = await d1Execute(ctx, install, configFile, `UPDATE api_keys SET revoked_at = ${Date.now()} WHERE revoked_at IS NULL AND ${where};`, "revoke API key");
+  if (!r2.changes) throw new Fail(`No active key ${which} on ${install.name}.`, { fix: `\`${CMD} api-key list\` shows the active ones.` });
+  const mine = ["api_key", "mcp_key"].filter((f) => install[f] && (install[f].startsWith(prefix) || /^\d+$/.test(which)));
+  if (mine.length && !/^\d+$/.test(which)) {
+    forgetInstallFields(ctx.cfg, install, mine);
+    save2(ctx);
+  }
+  end(`Revoked. Anything using that key stops working right away.`);
+}
+
+// src/commands/mcp.mjs
+import { spawnSync } from "node:child_process";
+var CLIENTS = ["claude", "cursor", "vscode", "codex", "windsurf", "other"];
+var claudeBin = () => process.env.DATABULL_CLAUDE_BIN || "claude";
+function hasClaude() {
+  if (process.env.DATABULL_CLAUDE_BIN === "") return false;
+  const r2 = spawnSync(claudeBin(), ["--version"], { stdio: "ignore", timeout: 1e4 });
+  return r2.status === 0;
+}
+function snippets(url, key) {
+  const header2 = `Authorization: Bearer ${key}`;
+  const json2 = (o2) => JSON.stringify(o2, null, 2);
+  return {
+    claude: { title: "Claude Code", where: "Run in a terminal", text: `claude mcp add --transport http --scope user databull ${url} --header "${header2}"` },
+    cursor: { title: "Cursor", where: "~/.cursor/mcp.json (or .cursor/mcp.json in a project)", text: json2({ mcpServers: { databull: { url, headers: { Authorization: `Bearer ${key}` } } } }) },
+    vscode: { title: "VS Code (Copilot agent mode)", where: '.vscode/mcp.json, or "MCP: Open User Configuration"', text: json2({ servers: { databull: { type: "http", url, headers: { Authorization: `Bearer ${key}` } } } }) },
+    codex: { title: "Codex", where: "~/.codex/config.toml", text: `[mcp_servers.databull]
+url = "${url}"
+http_headers = { "Authorization" = "Bearer ${key}" }` },
+    windsurf: { title: "Windsurf", where: "~/.codeium/windsurf/mcp_config.json", text: json2({ mcpServers: { databull: { serverUrl: url, headers: { Authorization: `Bearer ${key}` } } } }) },
+    other: { title: "Any other MCP client", where: "Streamable HTTP", text: `URL     ${url}
+Header  ${header2}` }
+  };
+}
+function addToClaude(url, key) {
+  const args = ["mcp", "add", "--transport", "http", "--scope", "user", "databull", url, "--header", `Authorization: Bearer ${key}`];
+  let r2 = spawnSync(claudeBin(), args, { encoding: "utf8", timeout: 3e4 });
+  if (r2.status !== 0 && /already exists/i.test(`${r2.stdout}${r2.stderr}`)) {
+    spawnSync(claudeBin(), ["mcp", "remove", "databull", "--scope", "user"], { encoding: "utf8", timeout: 3e4 });
+    r2 = spawnSync(claudeBin(), args, { encoding: "utf8", timeout: 3e4 });
+  }
+  return r2.status === 0 ? null : (r2.stderr || r2.stdout || "claude mcp add failed").trim().split("\n").pop();
+}
+async function runMcp(ctx, { pickInstall: pickInstall2, connect: connect2, runUpdate: runUpdate2, save: save2 }) {
+  const client = ctx.flags.client?.toLowerCase();
+  if (client && !CLIENTS.includes(client)) throw new Fail(`Unknown client "${ctx.flags.client}".`, { fix: `Use one of: ${CLIENTS.join(", ")}.` });
+  let url;
+  let key;
+  let install = null;
+  if (ctx.flags.url || process.env.DATABULL_URL) {
+    url = String(ctx.flags.url || process.env.DATABULL_URL).replace(/\/+$/, "").replace(/\/mcp$/, "");
+    key = ctx.flags.apiKey || process.env.DATABULL_API_KEY;
+    if (!key) throw new Fail("With --url, pass the key too (--api-key or DATABULL_API_KEY).", { fix: "Create one in your dashboard under Settings \u2192 API keys." });
+  } else {
+    install = await pickInstall2(ctx, { verb: "connect AI agents to" });
+    if (!install) throw new Fail("No DataBull install on this computer.", { fix: `Install it with \`${CMD}\`, or pass --url and --api-key (Settings \u2192 API keys in your dashboard).` });
+    await ensureAgentVersion(ctx, install, runUpdate2);
+    url = install.url;
+    key = install.mcp_key;
+    if (key) {
+      try {
+        await rpc({ url, key, install }, "ping");
+      } catch {
+        key = null;
+      }
+    }
+    if (!key) {
+      const made = await createKeyOnInstall(ctx, install, { label: `AI agents on ${hostName()}`, pii: !!ctx.flags.pii, connect: connect2 });
+      key = made.key;
+      install = { ...install, mcp_key: key };
+      upsertInstall(ctx.cfg, install);
+      save2(ctx);
+    }
+  }
+  const tools = await withStep(null, null, "Checking the connection", async () => {
+    const r2 = await rpc({ url, key, install }, "tools/list");
+    return { value: r2.tools, label: `${r2.tools.length} tools ready`, detail: url.replace(/^https:\/\//, "") };
+  }).then((r2) => r2.value);
+  const mcpUrl = `${url}/mcp`;
+  const all = snippets(mcpUrl, key);
+  let addedToClaude = false;
+  if ((!client || client === "claude") && hasClaude()) {
+    const go = ctx.flags.yes || canPrompt() && await askConfirm({ message: "Claude Code is installed. Add DataBull to it now (for all your projects)?" });
+    if (go) {
+      const err = addToClaude(mcpUrl, key);
+      if (err) warn(`Couldn't add it to Claude Code automatically: ${err}`, "Use the command below instead.");
+      else {
+        addedToClaude = true;
+        success(`Added to Claude Code. Open Claude Code and run ${import_picocolors3.default.bold("/mcp")} to see "databull" connected.`);
+      }
+    }
+  }
+  const show = client ? [client] : CLIENTS.filter((c) => !(c === "claude" && addedToClaude));
+  for (const c of show) {
+    const s = all[c];
+    box(`${s.title}  ${import_picocolors3.default.dim(s.where)}`, s.text.split("\n"));
+  }
+  line();
+  line(import_picocolors3.default.bold("Try asking your agent:"));
+  for (const q2 of ["Which referrer made me the most money this month?", "Compare this week with last week. What changed?", "Show my last 5 sales and where each buyer came from.", "Walk me through the journey of my latest customer."]) line(`  ${import_picocolors3.default.cyan(`\u201C${q2}\u201D`)}`);
+  line();
+  line(import_picocolors3.default.dim(`${tools.length} read-only tools: ${tools.map((t) => t.name).join(", ")}.`));
+  end(`The key is read-only${install ? `; revoke it any time with \`${CMD} api-key revoke ${key.slice(0, 12)}\`` : ""}. Docs: https://databull.app/docs/mcp`);
+}
+
 // src/index.mjs
-var VERSION = true ? "1.0.0" : "0.0.0-dev";
-var RUN = { install: runInstall, update: runUpdate, "reset-password": runReset, domain: runDomain, status: runStatus, license: runLicense, uninstall: runUninstall };
+var VERSION = true ? "1.1.0" : "0.0.0-dev";
+var DEPS = { pickInstall, connect, runUpdate, save };
+var RUN = {
+  install: runInstall,
+  update: runUpdate,
+  "reset-password": runReset,
+  domain: runDomain,
+  status: runStatus,
+  license: runLicense,
+  uninstall: runUninstall,
+  mcp: (ctx) => runMcp(ctx, DEPS),
+  "api-key": (ctx) => runApiKey(ctx, DEPS)
+};
 var NEEDS_WRANGLER = /* @__PURE__ */ new Set(["install", "update", "reset-password", "domain", "uninstall"]);
-var SUBTITLE = { install: "installer", update: "update", "reset-password": "reset password", domain: "custom domain", status: "status", license: "license", uninstall: "uninstall" };
+var LAZY_WRANGLER = /* @__PURE__ */ new Set(["mcp", "api-key", ...DATA_COMMANDS]);
+var SUBTITLE = { install: "installer", update: "update", "reset-password": "reset password", domain: "custom domain", status: "status", license: "license", uninstall: "uninstall", mcp: "AI agents", "api-key": "API keys" };
 function help() {
   const c = import_picocolors3.default;
-  const cmd = (name, text) => `  ${c.cyan(name.padEnd(16))}${text}`;
+  const cmd = (name, text) => `  ${c.cyan(name.padEnd(22))}${text}`;
   const flag = (name, text) => `  ${c.yellow(name.padEnd(28))}${text}`;
   return [
     "",
     `${c.bgBlue(c.white(c.bold(" DataBull ")))}  ${c.dim(`v${VERSION}`)}`,
     "",
-    "Install and update DataBull on your own Cloudflare account.",
+    "Install and update DataBull on your own Cloudflare account, and read your stats from the terminal or an AI agent.",
     "",
     `${c.bold("Usage")}  npx databull@latest ${c.dim("[command] [options]")}`,
     "",
@@ -2809,6 +3525,23 @@ function help() {
     cmd("uninstall", "Delete an install from Cloudflare"),
     cmd("help", "Show this help"),
     "",
+    c.bold("AI agents & API"),
+    cmd("mcp", "Connect Claude Code, Cursor, VS Code, Codex\u2026 to your stats"),
+    cmd("api-key", "create | list | revoke read-only API keys"),
+    "",
+    c.bold("Your stats") + c.dim("  (add --json for scripts and agents)"),
+    cmd("sites", "Every site: today, online now, 7 and 30 days"),
+    cmd("stats [site]", "Visitors, revenue, conversion\u2026 vs the previous period"),
+    cmd("sources [site]", "Referrers ranked by revenue (--dim channel|utm_campaign\u2026)"),
+    cmd("breakdown <dim>", "Rank any dimension: country, page, device, entry_page\u2026"),
+    cmd("compare [site]", "What changed vs the previous period, and why"),
+    cmd("sales [site]", "Recent sales and the source each one came from"),
+    cmd("visitors [site]", "Recent visitors (--customers for buyers only)"),
+    cmd("visitor <id>", "One visitor's journey: visits, pages, payments"),
+    cmd("live [site]", "Who's on the site right now"),
+    cmd("goals | funnels | ltv", "Goals, funnel steps, lifetime value by source"),
+    cmd("query <tool> [json]", "Call any agent tool and print its JSON"),
+    "",
     c.bold("Options"),
     flag("--key <key>", "License key (otherwise you are asked)"),
     flag("--account <id|name>", "Cloudflare account to use"),
@@ -2818,6 +3551,15 @@ function help() {
     flag("--no-open", "Don't open the browser; print links instead"),
     flag("--deactivate", "With license: free this activation"),
     flag("--delete-database", "With uninstall: also delete the database"),
+    flag("--period, -p <range>", "today, yesterday, 24h, 7d, 30d, mtd, last_month, ytd, 12m, all"),
+    flag("--from / --to <YYYY-MM-DD>", "Custom date range (in the site's time zone)"),
+    flag("--filter, -f <key=value>", "Repeatable: referrer=x.com, country=US, page=/pricing\u2026"),
+    flag("--by <metric>", "Sort: revenue, visitors, conversion (sources, breakdown, visitors)"),
+    flag("--limit, -n <n>", "How many rows"),
+    flag("--json", "Print the raw JSON (for scripts and agents)"),
+    flag("--url, --api-key", "Read another install (or set DATABULL_URL, DATABULL_API_KEY)"),
+    flag("--client <name>", "With mcp: claude, cursor, vscode, codex, windsurf, other"),
+    flag("--label <text>, --pii", "With api-key create: a name; allow customer details"),
     flag("--bundle <file.tgz>", "Use a local release bundle instead of downloading"),
     flag("--api <url>", "License server (default https://databull.app, env DATABULL_API)"),
     flag("--home <dir>", "Where DataBull keeps its files (default ~/.databull, env DATABULL_HOME)"),
@@ -2853,9 +3595,15 @@ Install the LTS version from https://nodejs.org (or \`brew install node\` on a M
   }
   const paths = resolvePaths(args.flags.home);
   const log = createLog(paths.logs);
-  const ctx = { version: VERSION, flags: args.flags, paths, log, api: apiBase(args.flags), cfg: null };
-  ctx.wrangler = NEEDS_WRANGLER.has(args.command) ? startTools(paths, log) : () => Promise.reject(new Error("wrangler not available for this command"));
+  const ctx = { version: VERSION, command: args.command, args: args.args, flags: args.flags, paths, log, api: apiBase(args.flags), cfg: null };
+  if (NEEDS_WRANGLER.has(args.command)) ctx.wrangler = startTools(paths, log);
+  else if (LAZY_WRANGLER.has(args.command)) {
+    let tools = null;
+    ctx.wrangler = () => (tools ||= startTools(paths, log))();
+    Object.defineProperty(ctx.wrangler, "ready", { get: () => !!tools?.ready });
+  } else ctx.wrangler = () => Promise.reject(new Error("wrangler not available for this command"));
   ctx.cfToken = tokenGetter(ctx);
+  if (DATA_COMMANDS.includes(args.command)) return runDataCommand(ctx);
   const onSigint = () => {
     killChildren();
     cleanupTemp();
@@ -2884,6 +3632,37 @@ Install the LTS version from https://nodejs.org (or \`brew install node\` on a M
     process.off("SIGTERM", onSigint);
   }
 }
+async function runDataCommand(ctx) {
+  process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
+  const onSigint = () => {
+    killChildren();
+    process.exit(130);
+  };
+  process.on("SIGINT", onSigint);
+  try {
+    ctx.cfg = readConfig(ctx.paths);
+    await runData(ctx, DEPS);
+    return 0;
+  } catch (err) {
+    stopSpinner();
+    if (err instanceof Cancelled) return 130;
+    ctx.log.section("failure");
+    ctx.log.write(err?.stack || String(err));
+    const message = err instanceof Fail ? err.message : `Something unexpected went wrong: ${err?.message || err}`;
+    const fix = err instanceof Fail ? err.fix : `Run it again; if it keeps happening, email adgan.business@gmail.com with ${ctx.log.path}.`;
+    if (ctx.flags.json) process.stdout.write(`${JSON.stringify({ error: message, ...fix ? { fix } : {} })}
+`);
+    process.stderr.write(`${import_picocolors3.default.red("\u2716")} ${message}
+${fix ? `  ${import_picocolors3.default.dim(fix)}
+` : ""}`);
+    return 1;
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+}
 
 // src/cli.mjs
 main(process.argv.slice(2)).then(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "databull",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Install and update DataBull, revenue-first web analytics, on your own Cloudflare account.",
   "type": "module",
   "bin": { "databull": "dist/databull.mjs" },
@@ -12,7 +12,7 @@
   "author": "DataBull <adgan.business@gmail.com>",
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node scripts/build.mjs && node --test test/unit.test.mjs test/install.test.mjs test/safety.test.mjs",
+    "test": "node scripts/build.mjs && node --test test/unit.test.mjs test/install.test.mjs test/safety.test.mjs test/agent.test.mjs",
     "prepublishOnly": "npm test"
   },
   "devDependencies": {