@erdoai/cli 0.82.0 → 0.84.0

package/dist/index.js

@@ -1,9 +1,24 @@
 #!/usr/bin/env node
 
+// src/refresh.ts
+function describeRefreshTrigger(state) {
+  if (state.disarmed) return "disarmed \u2014 the experiment has settled";
+  if (state.strategy === "live_webhook") return "incoming webhook events \u2014 page views do not trigger this feed";
+  if (state.strategy === "live_native_poll") return "not running \u2014 native polling is unavailable; configure script_js with a schedule or live_webhook";
+  if (!state.job_id) return "not running \u2014 no linked job; configure the refresh again";
+  if (state.job_enabled === false) return "not running \u2014 the linked job is disabled; configure the refresh again";
+  if (state.schedule) return state.schedule_enabled === false ? `cron ${state.schedule} is disabled` : `cron: ${state.schedule}`;
+  return state.refresh_on_view_enabled !== false ? "runs on view \u2014 when a bound page is opened and the data is stale" : "manual only \u2014 page views do not trigger this refresh";
+}
+function describeRefreshWrites(strategy, mode, key, liveMode) {
+  if (strategy?.startsWith("live_")) return liveMode === "append" ? "append \u2014 each incoming event adds rows" : "replace \u2014 each incoming event replaces the current rows";
+  return mode === "upsert" ? `upsert${key ? ` on ${key}` : ""} \u2014 rows outside what the recipe returns are kept` : "replace \u2014 rows the recipe does not return are deleted";
+}
+
 // src/index.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { basename } from "path";
-import { select } from "@inquirer/prompts";
+import { password, select } from "@inquirer/prompts";
 import { Command as Command2 } from "commander";
 
 // src/config.ts
@@ -539,6 +554,39 @@ var ErdoClient = class {
       `/v1/voice/sms-conversations/${encodeURIComponent(sessionID)}${qs ? `?${qs}` : ""}`
     );
   }
+  // The organization's business profile: its legal identity, which every A2P
+  // registration on the account is checked against. It follows the org
+  // convention rather than the voice one because it is the organization's, not
+  // any one number's.
+  getBusinessProfile() {
+    return this.request("GET", "/v1/org/business-profile");
+  }
+  // PUT rather than POST: there is exactly one profile per organization and a
+  // save replaces it, so a caller sending a partial body blanks what it omits.
+  setBusinessProfile(body) {
+    return this.request("PUT", "/v1/org/business-profile", body);
+  }
+  // The numbers the organization holds, with what each one's SMS registration
+  // is waiting on. Nothing here reaches the provider — the state is read from
+  // the row the registration action and the status cron maintain.
+  listVoicePhoneNumbers() {
+    return this.request("GET", "/v1/voice/phone-numbers");
+  }
+  getVoicePhoneNumberSMS(number) {
+    return this.request(
+      "GET",
+      `/v1/voice/phone-numbers/${encodeURIComponent(number)}/sms`
+    );
+  }
+  // Asking for a registration costs money at the carrier registry, so this
+  // files the same approval-gated action the chat agent files rather than
+  // registering anything itself.
+  provisionVoicePhoneNumberSMS(number) {
+    return this.request(
+      "POST",
+      `/v1/voice/phone-numbers/${encodeURIComponent(number)}/sms`
+    );
+  }
   // Run a read-only HogQL query against the org's page-analytics events. Rows are
   // positional per columns; enabled:false means page analytics is off for the org
   // (not zero traffic). A rejected query surfaces PostHog's message as the error.
@@ -1039,6 +1087,35 @@ var ErdoClient = class {
   listDatasetRevisions(slug) {
     return this.request("GET", `/v1/datasets/${encodeURIComponent(slug)}/revisions`);
   }
+  // --- dataset refreshes ---
+  // The configuration that keeps one dataset current — the recipe and the
+  // triggers that run it. A dataset nothing refreshes answers configured:false
+  // rather than 404, so an empty answer is still an answer.
+  getDatasetRefresh(slug) {
+    return this.request(
+      "GET",
+      `/v1/datasets/${encodeURIComponent(slug)}/refresh`
+    );
+  }
+  // Install or replace the whole configuration. Deterministic strategies are
+  // test-run before this returns and the outcome comes back on test_run — a
+  // recipe that saved but cannot run is not a working refresh.
+  setDatasetRefresh(slug, body) {
+    return this.request(
+      "PUT",
+      `/v1/datasets/${encodeURIComponent(slug)}/refresh`,
+      body
+    );
+  }
+  // Run the configured refresh once, now. It is asynchronous: this answers with
+  // the execution it started, and the outcome is read back from
+  // getDatasetRefresh.
+  runDatasetRefresh(slug) {
+    return this.request(
+      "POST",
+      `/v1/datasets/${encodeURIComponent(slug)}/refresh/run`
+    );
+  }
   // --- bounded outreach ---
   putOutreachBatch(batch, body) {
     return this.request(
@@ -1640,6 +1717,25 @@ function readMaybeFile(value) {
   if (value.startsWith("@@")) return value.slice(1);
   return value.startsWith("@") ? readFileSync2(value.slice(1), "utf8") : value;
 }
+async function resolveSecretInput(options) {
+  if (options.fromStdin) {
+    const piped = (await options.readStdin()).trim();
+    if (!piped) {
+      throw new Error("--tax-id-stdin was given but standard input was empty");
+    }
+    return piped;
+  }
+  const wanted = options.replace || !options.stored;
+  if (wanted && options.interactive) {
+    return (await options.prompt(options.stored)).trim() || void 0;
+  }
+  if (options.replace) {
+    throw new Error(
+      "--replace-tax-id needs a terminal to prompt on. In a script, pipe the value in instead: `... | erdo org business-profile set --tax-id-stdin`"
+    );
+  }
+  return void 0;
+}
 
 // src/scope.ts
 import { Option } from "commander";
@@ -1805,6 +1901,16 @@ function timedOutMessage(threadID) {
 function print(value) {
   console.log(JSON.stringify(value, null, 2));
 }
+async function readAllStdin() {
+  if (process.stdin.isTTY) {
+    throw new Error("nothing is piped to standard input");
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
 function readJSONObject(file, label) {
   let parsed;
   try {
@@ -2062,6 +2168,139 @@ org.command("autonomy [mode]").description("Show or set the org's engine-autonom
     fail(e);
   }
 });
+var businessProfileCmd = org.command("business-profile").description("The org's legal identity, which A2P SMS registration is checked against");
+function printBusinessProfile(profile) {
+  printAlignedTable(
+    ["field", "value"],
+    [
+      ["legal name", profile.legal_name],
+      ["entity type", profile.entity_type],
+      ["legal structure", profile.legal_structure],
+      // Only shown for the one entity type that has them, so a private
+      // company's table does not carry two rows reading "—".
+      ...profile.stock_exchange || profile.stock_ticker ? [
+        ["stock exchange", profile.stock_exchange],
+        ["stock ticker", profile.stock_ticker]
+      ] : [],
+      ["tax id", profile.tax_id_stored ? `stored, ending ${profile.tax_id_last4 || "????"}` : "none stored"],
+      ["street", profile.street],
+      ["city", profile.city],
+      ["region", profile.region],
+      ["postal code", profile.postal_code],
+      ["country", profile.country],
+      ["website", profile.website_url],
+      ["industry", profile.industry],
+      ["privacy policy", profile.privacy_policy_url],
+      ["terms", profile.terms_and_conditions_url],
+      ["representative", `${profile.representative_first_name} ${profile.representative_last_name}`.trim()],
+      ["title", profile.representative_title],
+      ["job position", profile.representative_job_position],
+      ["email", profile.representative_email],
+      ["phone", profile.representative_phone],
+      ["updated", profile.updated_at ?? ""]
+    ]
+  );
+}
+function printMissingProfileFields(missing) {
+  if (missing.length === 0) return;
+  console.log("");
+  console.log(`Still needed before a number can be registered: ${missing.join(", ")}`);
+  console.log("Fill them in with: erdo org business-profile set --help");
+}
+businessProfileCmd.command("get").description("Show the stored business profile and what SMS registration still needs").option(
+  "--json",
+  "print the raw JSON result, which also carries the accepted entity types, legal structures, industries and job positions"
+).action(async (opts) => {
+  try {
+    const res = await new ErdoClient().getBusinessProfile();
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    if (!res.exists) {
+      console.log("No business profile saved for this organization.");
+      if (res.missing_fields.length > 0) {
+        console.log(`Registration needs: ${res.missing_fields.join(", ")}`);
+      }
+      console.log("Save one with: erdo org business-profile set --help");
+      return;
+    }
+    printBusinessProfile(res.profile);
+    printMissingProfileFields(res.missing_fields);
+  } catch (e) {
+    fail(e);
+  }
+});
+businessProfileCmd.command("set").description("Save the organization's business profile (unset flags keep what is stored)").option("--legal-name <name>", "registered legal name, exactly as it appears on the tax record").option(
+  "--entity-type <type>",
+  "private_for_profit, public_for_profit, non_profit, sole_proprietor or government"
+).option(
+  "--legal-structure <value>",
+  "the legal form the carrier registry checks against the tax record: sole_proprietorship, partnership, limited_liability_corporation, co_operative, non_profit_corporation or corporation"
+).option("--stock-exchange <exchange>", "a public company's exchange, e.g. NYSE \u2014 required for public_for_profit").option("--stock-ticker <ticker>", "a public company's ticker, e.g. ACME \u2014 required for public_for_profit").option(
+  "--replace-tax-id",
+  "replace the stored tax id: prompts for the new EIN without echoing it. Omit to keep what is stored"
+).option(
+  "--tax-id-stdin",
+  "read the tax id from standard input instead of prompting, for a script \u2014 e.g. `pass show ein | erdo org business-profile set --tax-id-stdin`"
+).option("--street <street>", "street address of the registered business").option("--city <city>", "city of the registered business").option("--region <region>", "state or province, e.g. FL").option("--postal-code <code>", "postal or ZIP code").option("--country <iso2>", "two-letter ISO country code, e.g. US").option("--website-url <url>", "the business's own website \u2014 carriers check that it describes it").option("--industry <industry>", "one of the industries listed by: erdo org business-profile get --json").option("--privacy-policy-url <url>", "the business's own privacy policy page (https) \u2014 a campaign without one is rejected").option("--terms-url <url>", "the business's own terms and conditions page (https) \u2014 required for the same reason").option("--first-name <name>", "given name of the person carriers may contact").option("--last-name <name>", "family name of that person").option("--title <title>", "their job title in the business's own words, e.g. Managing Partner").option(
+  "--job-position <position>",
+  "their role from the fixed list (ceo, cfo, director, general_counsel, gm, vp, other)"
+).option("--email <email>", "their email address").option("--phone <number>", "their phone number in E.164, e.g. +13055550123").option("--json", "print the raw JSON result instead of a table").action(
+  async (opts) => {
+    try {
+      const api = new ErdoClient();
+      const current = await api.getBusinessProfile();
+      const stored = current.profile;
+      const taxID = await resolveSecretInput({
+        replace: opts.replaceTaxId === true,
+        stored: stored.tax_id_stored,
+        fromStdin: opts.taxIdStdin === true,
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        readStdin: readAllStdin,
+        prompt: (replacing) => password({
+          message: replacing ? "New business tax id (EIN \u2014 digits; it replaces the stored one):" : "Business tax id (EIN \u2014 digits; leave blank if the business has none):",
+          mask: "*"
+        })
+      });
+      const entityType = opts.entityType ?? stored.entity_type;
+      const isPublic = entityType === "public_for_profit";
+      const body = {
+        legal_name: opts.legalName ?? stored.legal_name,
+        entity_type: entityType,
+        legal_structure: opts.legalStructure ?? stored.legal_structure,
+        stock_exchange: isPublic ? opts.stockExchange ?? stored.stock_exchange : void 0,
+        stock_ticker: isPublic ? opts.stockTicker ?? stored.stock_ticker : void 0,
+        tax_id: taxID,
+        street: opts.street ?? stored.street,
+        city: opts.city ?? stored.city,
+        region: opts.region ?? stored.region,
+        postal_code: opts.postalCode ?? stored.postal_code,
+        country: opts.country ?? stored.country,
+        website_url: opts.websiteUrl ?? stored.website_url,
+        industry: opts.industry ?? stored.industry,
+        privacy_policy_url: opts.privacyPolicyUrl ?? stored.privacy_policy_url,
+        terms_and_conditions_url: opts.termsUrl ?? stored.terms_and_conditions_url,
+        representative_first_name: opts.firstName ?? stored.representative_first_name,
+        representative_last_name: opts.lastName ?? stored.representative_last_name,
+        representative_title: opts.title ?? stored.representative_title,
+        representative_job_position: opts.jobPosition ?? stored.representative_job_position,
+        representative_email: opts.email ?? stored.representative_email,
+        representative_phone: opts.phone ?? stored.representative_phone
+      };
+      const res = await api.setBusinessProfile(body);
+      if (opts.json) {
+        print(res);
+        return;
+      }
+      console.log("Business profile saved.");
+      printBusinessProfile(res.profile);
+      printMissingProfileFields(res.missing_fields);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
 var managed = org.command("managed").description("Operate client orgs via a manager account");
 managed.command("list").description("List the client orgs your org manages").action(async () => {
   try {
@@ -4891,7 +5130,7 @@ sentEmailsCmd.command("get <emailID>").description("Read one sent email, includi
     fail(e);
   }
 });
-var voiceCmd = program.command("voice").description("Read a voice agent's phone calls, text conversations and website widget conversations");
+var voiceCmd = program.command("voice").description("A voice agent's phone calls, text conversations, website widget conversations, and its numbers");
 function contactLabel(contact) {
   if (!contact) return "-";
   const name = [contact.first_name, contact.last_name].filter(Boolean).join(" ");
@@ -5134,6 +5373,123 @@ voiceSMSCmd.command("get <sessionID>").description("Read one SMS conversation: i
     }
   }
 );
+var voiceNumbersCmd = voiceCmd.command("numbers").description("The organization's phone numbers and their A2P SMS registration state");
+function printRegistrationState(registration) {
+  if (registration === null || typeof registration !== "object") {
+    if (registration !== void 0) print(registration);
+    return;
+  }
+  const state = registration;
+  printAlignedTable(
+    ["number", "kind", "status", "waiting on", "reason"],
+    [
+      [
+        state.address ?? "",
+        state.sender_kind ?? "",
+        state.status ?? "",
+        state.next_step ?? "",
+        state.reason ?? ""
+      ]
+    ]
+  );
+  printProfileDriftNote([state]);
+}
+function printProfileDriftNote(numbers) {
+  const drifted = numbers.filter((n) => n.profile_out_of_date);
+  if (drifted.length === 0) return;
+  console.log("");
+  for (const number of drifted) {
+    const fields = number.profile_out_of_date_fields ?? [];
+    console.log(
+      `${number.address ?? "this number"}: the business profile has changed since it was registered${fields.length > 0 ? ` (${fields.join(", ")})` : ""} \u2014 the carriers still hold the previous legal identity.`
+    );
+  }
+  console.log(
+    "Re-send it with: erdo voice numbers provision-sms <number>. It re-opens carrier review, which takes days."
+  );
+}
+voiceNumbersCmd.command("list").description("List the organization's numbers with what each one's SMS registration is waiting on").option("--json", "print the raw JSON result instead of a table").action(async (opts) => {
+  try {
+    const res = await new ErdoClient().listVoicePhoneNumbers();
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    const numbers = res.numbers ?? [];
+    if (numbers.length === 0) {
+      console.log("This organization holds no phone numbers.");
+    } else {
+      printAlignedTable(
+        ["number", "agent", "kind", "status", "waiting on", "reason"],
+        numbers.map((n) => [
+          n.address,
+          n.agent_ref ?? "",
+          n.sender_kind,
+          n.status,
+          n.next_step ?? "",
+          n.reason ?? ""
+        ])
+      );
+      process.stderr.write(`showing ${numbers.length} number(s)
+`);
+      printProfileDriftNote(numbers);
+    }
+    if (!res.business_profile_complete) {
+      console.log("");
+      console.log(
+        res.missing_profile_fields.length > 0 ? `The business profile is incomplete \u2014 registration needs: ${res.missing_profile_fields.join(", ")}` : "The business profile is incomplete \u2014 no profile has been saved yet."
+      );
+      console.log("Complete it with: erdo org business-profile set --help, or in Settings \u2192 Business.");
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+voiceNumbersCmd.command("get <number>").description("Read one number's SMS registration state and what it is waiting on").option("--json", "print the raw JSON result instead of a summary").action(async (number, opts) => {
+  try {
+    const res = await new ErdoClient().getVoicePhoneNumberSMS(number);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    printRegistrationState(res);
+    if (res.missing_profile_fields && res.missing_profile_fields.length > 0) {
+      console.log("");
+      console.log(
+        `The business profile is incomplete \u2014 registration needs: ${res.missing_profile_fields.join(", ")}`
+      );
+      console.log("Complete it with: erdo org business-profile set --help, or in Settings \u2192 Business.");
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+voiceNumbersCmd.command("provision-sms <number>").description("Ask for A2P SMS registration of one of the organization's numbers").option("--json", "print the raw JSON result instead of a summary").action(async (number, opts) => {
+  try {
+    const res = await new ErdoClient().provisionVoicePhoneNumberSMS(number);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    if (res.status === "pending_approval") {
+      console.log("Nothing has been registered yet \u2014 an approval card was filed and awaits a decision.");
+      if (res.action_display) console.log(`action: ${res.action_display}`);
+      if (res.approval_request_id) {
+        console.log(`approval request: ${res.approval_request_id}`);
+        console.log(`  erdo approvals show ${res.approval_request_id}`);
+        console.log(`  erdo approvals decide ${res.approval_request_id} --approve`);
+      }
+    } else {
+      console.log(`Registration ${res.status}.`);
+      printRegistrationState(res.registration);
+    }
+    process.stderr.write(
+      "Carrier review takes days once submitted; the status updates on its own \u2014 re-read it with: erdo voice numbers list\n"
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
 var datasetsCmd = program.command("datasets").description("Datasets");
 datasetsCmd.command("list").description("List datasets").option(
   "--class <class>",
@@ -5369,6 +5725,232 @@ datasetsCmd.command("configure-integration <dataset-id>").description("Set an in
     fail(e);
   }
 });
+var refreshCmd = datasetsCmd.command("refresh").description(
+  "The recipe that keeps a dataset current, and the triggers that run it \u2014 read it with `show`, install or replace it with `set`, and run it once now with `run`"
+);
+var REFRESH_STRATEGIES = ["script", "script_js", "agent_run", "live_webhook"];
+function readRefreshJSONFile(value, label) {
+  return readJSONObject(value.startsWith("@") ? value.slice(1) : value, label);
+}
+refreshCmd.command("show <slug>").description(
+  "Show what keeps a dataset current \u2014 which recipe runs, whether it replaces or merges rows, what triggers it, and how its last run went. A dataset nothing refreshes says so plainly instead of erroring, because 'nothing keeps this current' is the answer most worth reading. The recipe's own source is not printed here; --json carries it."
+).option("--json", "print the raw JSON result instead of a table").action(async (slug, opts) => {
+  try {
+    const res = await new ErdoClient().getDatasetRefresh(slug);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    if (!res.configured) {
+      console.log(
+        `Nothing keeps ${res.dataset_slug} current \u2014 its rows change only when something writes to it. Install a recipe with: erdo datasets refresh set ${res.dataset_slug} --strategy script_js --transform-js @refresh.js`
+      );
+      return;
+    }
+    const rows = [];
+    rows.push(["strategy", res.strategy || "(none recorded)"]);
+    rows.push(["writes", describeRefreshWrites(res.strategy, res.refresh_mode, res.key_column, res.live_write_mode)]);
+    rows.push(["trigger", describeRefreshTrigger(res)]);
+    if (res.schedule) {
+      const zone = res.schedule_timezone || "UTC";
+      rows.push([
+        "cron",
+        res.schedule_enabled ? `${res.schedule} (${zone})` : `${res.schedule} (${zone}) \u2014 DISARMED, this cron is not firing`
+      ]);
+    } else {
+      rows.push(["cron", "none"]);
+    }
+    rows.push([
+      "on view",
+      res.refresh_on_view_enabled ? `yes \u2014 opening a page bound to this dataset refreshes it once the data is over ${res.refresh_on_view_stale_after_seconds}s old, at most once every ${res.refresh_on_view_debounce_seconds}s` : "no \u2014 opening a page bound to this dataset never triggers a refresh"
+    ]);
+    if (res.disarmed) {
+      rows.push([
+        "disarmed",
+        "yes \u2014 the platform stopped this schedule after the measurement it fed settled"
+      ]);
+    }
+    if (res.last_refresh_at || res.last_refresh_status) {
+      const parts = [res.last_refresh_status || "status not recorded"];
+      if (res.last_refresh_at) parts.push(res.last_refresh_at);
+      if (res.last_refresh_duration_ms !== void 0) {
+        parts.push(`${res.last_refresh_duration_ms} ms`);
+      }
+      rows.push(["last run", parts.join("  ")]);
+      if (res.last_refresh_error) rows.push(["last error", res.last_refresh_error]);
+    } else {
+      rows.push(["last run", "never \u2014 this refresh has not run yet"]);
+    }
+    if (res.live_write_mode) rows.push(["live write mode", res.live_write_mode]);
+    if (res.action_key) rows.push(["action", res.action_key]);
+    if (res.poll_interval_ms !== void 0) {
+      rows.push(["poll interval", `${res.poll_interval_ms} ms`]);
+    }
+    if (res.context_dataset_ids?.length) {
+      rows.push([
+        "context datasets",
+        `${res.context_dataset_ids.length} other dataset(s) the recipe reads`
+      ]);
+    }
+    for (const [label, source] of [
+      ["script (python)", res.script],
+      ["transform_js", res.transform_js],
+      ["agent prompt", res.agent_prompt]
+    ]) {
+      if (source) rows.push(["recipe", `${label}, ${source.length} characters`]);
+    }
+    if (res.job_id) rows.push(["job", res.job_id]);
+    printAlignedTable(["setting", "value"], rows);
+    if (!res.strategy?.startsWith("live_") && res.job_id && res.job_enabled !== false && !res.disarmed && !res.schedule && !res.refresh_on_view_enabled) {
+      console.log(
+        `
+Nothing triggers this refresh on its own \u2014 it runs only when asked: erdo datasets refresh run ${res.dataset_slug}`
+      );
+    }
+    if (res.script || res.transform_js || res.agent_prompt) {
+      console.log(`
+Read the recipe with: erdo datasets refresh show ${res.dataset_slug} --json`);
+    }
+  } catch (e) {
+    fail(e);
+  }
+});
+refreshCmd.command("set <slug>").description(
+  "Install or replace the refresh that keeps a dataset current. This writes the whole configuration, so pass everything the strategy needs in one call \u2014 what you omit is what that strategy does not use. Omitting --schedule is the default and cheapest behaviour: the dataset refreshes when somebody opens a page bound to it and the data is stale, and never runs while nobody is looking; add a cron only when the data must be fresh for something that is not a viewer. --mode replace deletes the rows the recipe did not return, so anything time-series or incremental wants --mode upsert --key-column <c>, which merges by that key and leaves rows outside the returned window alone. Deterministic strategies are test-run before this returns; a recipe that saves but cannot run exits non-zero rather than reporting success."
+).requiredOption(
+  "--strategy <s>",
+  `how the refresh runs: ${REFRESH_STRATEGIES.join(", ")}. script_js is JavaScript and the usual choice for fetch-and-reshape; script is Python, for when the recipe needs pandas or numpy; agent_run hands the job to an LLM agent and is the expensive last resort; live_webhook is a push-driven feed; native polling is unavailable`
+).option(
+  "--mode <replace|upsert>",
+  "replace overwrites every row with what the recipe returned; upsert merges by --key-column and keeps rows outside the returned window. Omit it and you get upsert when you passed --key-column and replace when you did not, since a key column is only meaningful to a merge"
+).option("--key-column <c>", "the column an upsert merges on; required with --mode upsert").option(
+  "--schedule <cron>",
+  "a cron expression to run the refresh on a fixed cadence. Omit it and the refresh runs on view instead \u2014 cheaper, because it never runs while nobody is looking"
+).option("--timezone <tz>", "IANA timezone the cron expression is read in (default UTC)").option(
+  "--script <pyOr@file>",
+  "Python source for the script strategy, inline or @path; it must call emit_dataset(df) or emit_rows(rows)"
+).option("--script-entrypoint <f>", "entrypoint filename for the script strategy (default main.py)").option(
+  "--transform-js <jsOr@file>",
+  "JavaScript source, inline or @path. script_js enters at function refresh(ctx) returning rows; the live strategies enter at function transform(raw) reshaping one event"
+).option("--agent-prompt <textOr@file>", "instructions for the agent_run strategy, inline or @path").option(
+  "--context-datasets <csv>",
+  "slugs of other datasets the recipe reads besides the one it writes"
+).option(
+  "--on-view",
+  "let a page view trigger this refresh (the platform default); pass --no-on-view to turn it off. Sent only when you pass one of the two"
+).option("--no-on-view", "stop page views from triggering this refresh").option(
+  "--stale-after <seconds>",
+  "how old the data must be before a page view triggers a refresh",
+  (v) => parseInt(v, 10)
+).option(
+  "--debounce <seconds>",
+  "minimum gap between two view-triggered refreshes",
+  (v) => parseInt(v, 10)
+).option(
+  "--live-write-mode <append|replace>",
+  "for the live strategies: append for a time-series that accumulates, replace for current state that overwrites on each event"
+).option("--payload-schema <@file>", "JSON file: a schema the transformed row must match").option(
+  "--sample-payload <@file>",
+  "JSON file: an example upstream payload, used to test-run transform_js at configure time"
+).option(
+  "--parameters <@file>",
+  "JSON file: all configuration values for this recipe; omitting clears previous PARAMETERS values"
+).action(
+  async (slug, opts) => {
+    try {
+      if (!REFRESH_STRATEGIES.includes(opts.strategy)) {
+        fail(
+          new Error(
+            `--strategy must be one of: ${REFRESH_STRATEGIES.join(", ")} (got ${JSON.stringify(opts.strategy)})`
+          )
+        );
+        return;
+      }
+      if (opts.mode && opts.mode !== "replace" && opts.mode !== "upsert") {
+        fail(new Error("--mode must be replace or upsert"));
+        return;
+      }
+      if (opts.mode === "upsert" && !opts.keyColumn) {
+        fail(new Error("--mode upsert needs --key-column <c>: the column the merge keys on"));
+        return;
+      }
+      const body = { strategy: opts.strategy };
+      if (opts.mode) body.refresh_mode = opts.mode;
+      if (opts.keyColumn) body.key_column = opts.keyColumn;
+      if (opts.schedule) body.schedule = opts.schedule;
+      if (opts.timezone) body.timezone = opts.timezone;
+      const script = readMaybeFile(opts.script);
+      if (script !== void 0) body.script = script;
+      if (opts.scriptEntrypoint) body.script_entrypoint = opts.scriptEntrypoint;
+      const transformJS = readMaybeFile(opts.transformJs);
+      if (transformJS !== void 0) body.transform_js = transformJS;
+      const agentPrompt = readMaybeFile(opts.agentPrompt);
+      if (agentPrompt !== void 0) body.agent_prompt = agentPrompt;
+      if (opts.contextDatasets) {
+        const slugs = opts.contextDatasets.split(",").map((s) => s.trim()).filter(Boolean);
+        if (slugs.length) body.context_dataset_slugs = slugs;
+      }
+      if (typeof opts.onView === "boolean") body.refresh_on_view_enabled = opts.onView;
+      if (opts.staleAfter !== void 0) body.refresh_on_view_stale_after_seconds = opts.staleAfter;
+      if (opts.debounce !== void 0) body.refresh_on_view_debounce_seconds = opts.debounce;
+      if (opts.liveWriteMode) body.live_write_mode = opts.liveWriteMode;
+      if (opts.payloadSchema) {
+        body.payload_schema = readRefreshJSONFile(opts.payloadSchema, "--payload-schema");
+      }
+      if (opts.samplePayload) {
+        body.sample_payload = readRefreshJSONFile(opts.samplePayload, "--sample-payload");
+      }
+      if (opts.parameters) {
+        body.parameters = readRefreshJSONFile(opts.parameters, "--parameters");
+      }
+      const res = await new ErdoClient().setDatasetRefresh(slug, body);
+      console.log(
+        `Installed a ${res.strategy} refresh on ${res.dataset_slug}${res.previous_strategy ? ` (replacing ${res.previous_strategy})` : ""}`
+      );
+      console.log(`writes: ${describeRefreshWrites(res.strategy, res.refresh_mode, body.key_column, body.live_write_mode)}`);
+      console.log(describeRefreshTrigger({ ...res, refresh_on_view_enabled: body.refresh_on_view_enabled }));
+      if (res.job_id) console.log(`job: ${res.job_id}`);
+      if (res.webhook_url) {
+        console.log(`webhook url: ${res.webhook_url}`);
+        if (res.webhook_secret) {
+          console.log(`webhook secret: ${res.webhook_secret}`);
+          console.log("The secret is shown once, here \u2014 it is never returned again; store it now.");
+        }
+      }
+      if (res.test_run) {
+        if (res.test_run.success) {
+          console.log(`test run: passed in ${res.test_run.duration_ms} ms`);
+        } else {
+          console.error(
+            `test run: FAILED after ${res.test_run.duration_ms} ms \u2014 ${res.test_run.error || "no error reported"}`
+          );
+          console.error(
+            "The configuration is saved but the recipe does not run. Fix it and re-run this command."
+          );
+          process.exitCode = 1;
+        }
+      }
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+refreshCmd.command("run <slug>").description(
+  "Run a dataset's configured refresh once, now \u2014 the same recipe a cron or a page view would run, without waiting for either. It is asynchronous: this answers with the execution it started, and `datasets refresh show <slug>` carries the outcome once it finishes."
+).option("--json", "print the raw JSON result instead of a summary").action(async (slug, opts) => {
+  try {
+    const res = await new ErdoClient().runDatasetRefresh(slug);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    console.log(`Started a ${res.strategy} refresh of ${res.dataset_slug} (${res.status})`);
+    console.log(`execution: ${res.job_execution_id}`);
+    console.log(`Check how it went with: erdo datasets refresh show ${res.dataset_slug}`);
+  } catch (e) {
+    fail(e);
+  }
+});
 var analytics = program.command("analytics").description("Page analytics \u2014 what is tracking your published pages, and how they perform with real visitors");
 analytics.command("query <hogql>").description("Run a read-only HogQL query against this org's page-analytics events").option("--json", "print the raw JSON result instead of a table").action(async (hogql, opts) => {
   try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erdoai/cli",
-  "version": "0.82.0",
-  "description": "Erdo CLI \u2014 drive datasets, pages, and evals from the terminal or CI",
+  "version": "0.84.0",
+  "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {
     "erdo": "dist/index.js"
@@ -53,4 +53,4 @@
   "overrides": {
     "esbuild": "^0.28.1"
   }
-}
+}