@wrangled/cli 0.3.53 → 0.3.57

package/dist/api.js

@@ -21,6 +21,8 @@ export class UnreadableCredentialsError extends CliError {
  * in src/lib/knowledge/tags.ts. format's flag is --ad-format, because --format picks the output.
  */
 export const entryTagFlags = { angle: "angle", hook_kind: "hook-kind", format: "ad-format", awareness: "awareness" };
+/** Mirrors PUSH_MAX_DEFAULT, PUSH_MAX_CEILING and PUSH_CSV_MAX_BYTES in src/lib/outbound/model.ts. */
+export const OUTBOUND_PUSH_MAX = { default: 5000, ceiling: 50_000, csvBytes: 4 * 1024 * 1024 };
 /** The most ads or ad sets one meta ads|adset pause|resume sends; the server refuses more. */
 export const META_IDS_MAX = 10;
 /** The most ads or ad groups one google-ads ads|adgroup pause|resume sends; the server refuses more. */
@@ -30,6 +32,16 @@ export const MESSAGE_CREDIT_DAYS = 7;
 /** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */
 export const IMPORT_LIMITS = { bytes: 50 * 1024 * 1024, rows: 1_000_000, columns: 500 };
 export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+/** Copies of the server's AGENT_TABLE_LIMITS and agent table name rule; src/lib/cli-consistency.test.ts keeps them in step. */
+export const AGENT_TABLE_LIMITS = {
+    tables: 50,
+    rowsPerTable: 1_000_000,
+    bytes: 500 * 1024 * 1024,
+    batchRows: 10_000,
+    batchBytes: 10 * 1024 * 1024,
+    columns: 500,
+};
+export const AGENT_TABLE_NAME_PATTERN = /^[a-z0-9_]{1,48}$/;
 /** `configHome` defaults to $XDG_CONFIG_HOME, or ~/.config. */
 export function credentialsPath(configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")) {
     return join(configHome, brand.slug, "credentials.json");

package/dist/articles.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { CliError, exitCodes } from "./api.js";
+// As the server reads an article (src/lib/publishing/wordpress/html.ts): a tag ends at the first > outside quotes.
+const IMG_TAG = /<img\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+const ATTRIBUTE = /(\s+)([^\s"'>/=]+)(?:(\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+/**
+ * Points each <img src> that names a --file (as given, or by its file name) at that file as sha256:<its SHA-256>,
+ * the reference a publisher replaces with the address the file gets where it is published. Other sources are left.
+ */
+export function pointImagesAtFiles(html, files) {
+    if (files.length === 0)
+        return html;
+    const refs = new Map();
+    for (const { path, data } of files) {
+        const ref = `sha256:${createHash("sha256").update(data).digest("hex")}`;
+        for (const name of [path, basename(path), `./${basename(path)}`])
+            refs.set(name, ref);
+    }
+    return html.replace(IMG_TAG, (tag) => {
+        let seen = false;
+        return tag.replace(ATTRIBUTE, (whole, space, name, equals, double, single, bare) => {
+            if (seen || name.toLowerCase() !== "src" || equals === undefined)
+                return whole;
+            seen = true;
+            const ref = refs.get((double ?? single ?? bare ?? "").trim());
+            if (ref === undefined)
+                return whole;
+            const quote = single !== undefined ? "'" : '"';
+            return `${space}${name}${equals}${quote}${ref}${quote}`;
+        });
+    });
+}
+const WORDPRESS = "wordpress:";
+/**
+ * The publisher and target `content publish` sends. `--to wordpress:<site>` fills the target itself, with --status
+ * draft (the default) or publish; any other publisher takes its target as --target JSON, given here parsed.
+ */
+export function publishDestination(to, { target, status }) {
+    if (to.startsWith(WORDPRESS)) {
+        if (target !== undefined)
+            throw new CliError("--to wordpress:<site> sets the target itself; leave out --target.", exitCodes.usage);
+        const site = to.slice(WORDPRESS.length);
+        return { publisher: "wordpress", target: status === undefined ? { site } : { site, status } };
+    }
+    if (status !== undefined)
+        throw new CliError("--status goes with --to wordpress:<site>.", exitCodes.usage);
+    if (target === undefined)
+        throw new CliError(`--to ${to} needs --target '<json>'.`, exitCodes.usage);
+    return { publisher: to, target };
+}

package/dist/enrich.js

@@ -0,0 +1,101 @@
+import { CliError, exitCodes } from "./api.js";
+/** The most people one find-email request takes; `enrich email` sends a longer file in batches of this many. */
+export const FIND_EMAIL_PEOPLE_MAX = 25;
+export const ENRICH_EMAIL_USAGE = "enrich email --file <people.csv | people.json> [--steps <tool,tool>]";
+const COLUMNS = ["firstName", "lastName", "domain", "companyName", "linkedinUrl"];
+const usage = (problem) => new CliError(`${problem}\nUsage: ${ENRICH_EMAIL_USAGE}`, exitCodes.usage);
+/** RFC 4180 rows: quoted fields may hold commas, doubled quotes and line breaks. */
+function csvRows(text) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (quoted) {
+            if (char === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (char === '"')
+                quoted = false;
+            else
+                field += char;
+        }
+        else if (char === '"')
+            quoted = true;
+        else if (char === ",") {
+            row.push(field);
+            field = "";
+        }
+        else if (char === "\n" || char === "\r") {
+            if (char === "\r" && text[i + 1] === "\n")
+                i++;
+            rows.push([...row, field]);
+            row = [];
+            field = "";
+        }
+        else
+            field += char;
+    }
+    if (quoted)
+        throw usage("The CSV file has a quote that is never closed.");
+    if (field !== "" || row.length > 0)
+        rows.push([...row, field]);
+    return rows.filter((cells) => cells.some((cell) => cell.trim() !== ""));
+}
+function fromCsv(text) {
+    const [header, ...rows] = csvRows(text.replace(/^/, ""));
+    if (!header)
+        throw usage("The CSV file is empty.");
+    const names = header.map((name) => name.trim());
+    const unknown = names.filter((name) => !COLUMNS.includes(name));
+    if (unknown.length > 0)
+        throw usage(`Unknown CSV column ${unknown.map((n) => JSON.stringify(n)).join(", ")}; the columns are ${COLUMNS.join(", ")}.`);
+    return rows.map((cells) => Object.fromEntries(names.flatMap((name, i) => (cells[i]?.trim() ? [[name, cells[i].trim()]] : []))));
+}
+function fromJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw usage("The JSON file is not valid JSON.");
+    }
+    const people = Array.isArray(parsed) ? parsed : parsed?.people;
+    if (!Array.isArray(people))
+        throw usage('The JSON file must be a list of people, or {"people": [...]}.');
+    return people;
+}
+/** The people in a `.json` file (a list, or {people: [...]}) or a CSV file whose header names the columns. The server checks each person. */
+export function parsePeople(text, path) {
+    const people = path.toLowerCase().endsWith(".json") ? fromJson(text) : fromCsv(text);
+    if (people.length === 0)
+        throw usage("The file lists no people.");
+    return people;
+}
+/** --steps as the list of tool ids, or undefined for every step. */
+export function parseSteps(flag) {
+    if (flag === undefined)
+        return undefined;
+    const steps = flag.split(",").map((step) => step.trim()).filter(Boolean);
+    if (steps.length === 0)
+        throw usage("--steps names no tools.");
+    return steps;
+}
+export function batches(items, size = FIND_EMAIL_PEOPLE_MAX) {
+    return Array.from({ length: Math.ceil(items.length / size) }, (_, i) => items.slice(i * size, (i + 1) * size));
+}
+/** One printed row per person. */
+export function answerRow(answer) {
+    const { person } = answer;
+    return {
+        name: [person.firstName, person.lastName].filter(Boolean).join(" "),
+        domain: person.domain ?? person.companyName ?? person.linkedinUrl ?? "",
+        email: answer.email ?? "",
+        status: answer.status,
+        "found by": answer.foundBy ?? "",
+        cost: `${Math.round(answer.costCents * 100) / 100}¢`,
+        "run ids": answer.steps.flatMap((step) => (step.runId ? [step.runId] : [])).join(" "),
+    };
+}

package/dist/guide.js

@@ -1,4 +1,5 @@
-import { IMPORT_LIMITS, MESSAGE_CREDIT_DAYS } from "./api.js";
+import { FIND_EMAIL_PEOPLE_MAX } from "./enrich.js";
+import { AGENT_TABLE_LIMITS, IMPORT_LIMITS, MESSAGE_CREDIT_DAYS } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
 import { BACK_TAG_SKILL_NAME, CRO_SKILL_NAME, GRAMMAR_SKILL_NAME, LEARN_NAMES_SKILL_NAME, LESSONS_SKILL_NAME, MAP_OFFERS_SKILL_NAME, PLAYBOOK_CHOICES, STORY_SKILL_NAME, WEEKLY_LOOP_SKILL_NAME } from "./playbooks.js";
 import { PULL_STATE_FILE } from "./pull.js";
@@ -92,7 +93,7 @@ To find content, such as "the 10 emails with the best click rate", "our 5 best v
 
 - \`--text "<words>"\` finds words in the current version's subject, headline and body, or in a video's or call recording's transcript. Words are stemmed ("guarantee" finds "guaranteed"); use "quotes" for a phrase and -word to leave a word out.
 - \`--mode meaning\` finds content that means something close to \`--text\`, even in other words: \`--text "saves time"\` also finds "done in five minutes". Results come nearest first, each with its distance (0 is the same meaning) and the closest passage as its words. It takes no \`--sort\` or \`--order\`, and finds only content embedded so far (each hour, new versions and transcripts are embedded).
-- \`--kind\` (ad, email, sms, landing_page, video, social_post, conversation), \`--platform\` (meta, ghl, klaviyo, roezan, bayengage, activecampaign, mailchimp, hubspot, kit, instantly, kajabi, omnisend, google_ads, tiktok, microsoft_ads, pinterest, web, youtube, instagram, facebook_page, callrail, zoom, fathom, google_drive, ad_library, workspace, upload) and \`--origin\` (discovered or made) narrow it. \`--from\` and \`--to\` keep content live on those days: from its first day with numbers (or the day the library first saw it) to its last.
+- \`--kind\` (ad, email, sms, landing_page, video, social_post, article, conversation), \`--platform\` (meta, ghl, klaviyo, roezan, bayengage, activecampaign, mailchimp, hubspot, kit, instantly, kajabi, omnisend, google_ads, tiktok, microsoft_ads, pinterest, linkedin, web, wordpress, youtube, instagram, facebook_page, callrail, zoom, fathom, google_drive, ad_library, workspace, upload) and \`--origin\` (discovered or made) narrow it. \`--from\` and \`--to\` keep content live on those days: from its first day with numbers (or the day the library first saw it) to its last.
 - \`--sort\` is \`recent\` (the default, newest first) or any number in the \`content_scorecard\` view, such as \`click_rate\`, \`open_rate\`, \`roas\`, \`spend\` or their \`_30d\` twins for the last 30 days. Content with money in several currencies has a number per currency and sorts by its best. Content without that number comes last. \`--order asc\` turns it around; \`--limit\` is 1 to 50 (default 10).
 - Each result has the item's id or SKU, its words, how many files it has, whether it has a transcript, and its scorecard numbers. \`${cli} content show <sku | item-id>\` prints one item in full: its words, how many versions it has, its transcript and every number; \`--format json\` adds every version, and links to its files.
 - To add marketing that lives somewhere no source connects to, such as a sales video, a webinar recording, a script or an email from another tool, run \`${cli} content capture --kind <kind> --name <name>\` with \`--body\`, \`--file\`, \`--source\` (where it came from) and \`--url\`. It is kept as found, with no SKU, so it is never approved or published; \`--platform upload\` finds these. Videos and audio are transcribed on their own; give \`--transcript @file\` when you already have one, so none is paid for.
@@ -129,6 +130,10 @@ For "how is the funnel doing?", "which campaigns are working?" and "where does t
 - Money is never converted or added across currencies: there is one row per currency, and one total per currency. In \`${cli} funnel\`, leads and calls are counted for the whole period and repeat on every currency row, so never add them across its rows. In \`${cli} campaigns\`, each campaign's leads and calls sit on the row of the currency it spends in (or a blank-currency row when it has no spend), so they do add up across rows and totals. Ratios come from the summed numbers, not averages. An empty cell means the source is not connected, or a ratio would divide by 0.
 - To go deeper, query the views behind them: \`daily_funnel\`, \`campaign_results_daily\`, \`daily_spend\` and \`daily_sales\`. Their descriptions in \`${cli} warehouse schema\` say what each counts.
 
+## Page-two keywords
+
+\`${cli} seo page-two\` lists the Google searches where the client's site shows up, but only around positions 11 to 20: the searches closest to page one. It reads Google Search Console's \`gsc_search_daily\` over the last 90 days ending on the newest day it has, and keeps a search when its average position, weighted by impressions, is 11 to 20 and it was shown at least 100 times. Its click rate is its clicks over its impressions, never an average of daily rates. Each row is one property and search, with the page shown most for it; \`--by query-page\` gives one row per page instead. \`--site <site_url>\` reads one property (\`sc-domain:example.com\` or \`https://www.example.com/\`), \`--days <n>\` (at most 486), \`--from <n>\` and \`--to <n>\` the positions, \`--min-impressions <n>\`, and \`--limit <n>\` (1 to 500, default 50). Without Search Console data it says so instead of printing an empty list.
+
 ## Webhook addresses
 
 A webhook address lets a tool such as a form or webinar platform push events into the warehouse's \`raw_events\` table. \`${cli} intake list\` shows each address with whether it is on, how many days it keeps events, the events of the last 24 hours, the last event's time, and the rows it holds. \`${cli} intake create <label>\` makes one and prints its link, address and token. The link is the one URL to paste into the sending tool: the address with the token on the end, or for Mailgun the bare address. Add \`--kind ghl_workflow\` for a GoHighLevel workflow's Webhook step: its events also land, typed, in \`ghl_events\`. Add \`--kind aloware\` for Aloware's call and text webhooks: they also land, typed, in \`aloware_calls\` and \`aloware_texts\`. Add \`--kind webinarfuel\` or \`--kind stealth_seminar\` for a webinar tool: its sign-ups, attendance, replays and offer clicks land in \`webinar_events\`. Add \`--kind mailgun --signing-key-stdin\`, with Mailgun's HTTP webhook signing key piped on stdin, for a Mailgun account's webhooks: each event's signature is checked and alone proves the sender, so Mailgun posts to the address itself with no token, and its events also land, typed, in \`mailgun_events\`. When the account's key changes, pipe the new one to \`${cli} intake signing-key <id> --signing-key-stdin\`; deleting the workspace's last Mailgun address deletes the key. Add \`--kind thrivecart_events\` for a ThriveCart account's webhook: affiliate commissions earned, taken back and paid out also land, typed, in \`thrivecart_affiliate_commissions\`, where they stay after their events pass the retention, and \`daily_spend\` counts them. Add \`--kind roezan\` once the workspace's Roezan source is connected: the server uses the source's key to ask Roezan to send each new broadcast to the link (\`subscription\` in the answer says whether that worked; if not, add the link in Roezan's Webhooks tab), each broadcast an event names lands in \`roezan_broadcast_events\`, and the Roezan source reads it on its next hourly sync. The link and token are shown only then and after \`${cli} intake rotate <id>\`. Paste the link into the sending tool, or, when the tool can set a header, give it the address and \`Authorization: Bearer <token>\` instead, which keeps the token out of request logs. Never paste either anywhere else. Events are kept for 90 days unless \`--retention-days\` or \`${cli} intake retention <id> <days>\` says otherwise (1 to 3650). \`${cli} intake delete <id> --yes\` deletes the address and every event it saved. A website visit tag shows in \`${cli} intake list\` as an address of kind \`visit_tag\`, and each page view it records lands in \`site_visits\` (host, path, referrer host, UTM tags, click ids, country, device type, a bot flag and a random visitor id). \`${cli} intake create\` cannot make one: a tag has no token and needs its list of allowed sites, so an operator makes it with the server's \`npm run visit-tag:create\` script.
@@ -151,6 +156,33 @@ A webhook address lets a tool such as a form or webinar platform push events int
 - Limits: ${IMPORT_LIMITS.bytes / (1024 * 1024)} MB, ${IMPORT_LIMITS.rows.toLocaleString("en-US")} rows and ${IMPORT_LIMITS.columns} columns per file. A file over 4.5 MB, more than the hosted app takes in one request, goes to the workspace's private file storage first and is imported from there, then deleted; the command does this by itself.
 - The output lists the table, its row count, and each column with its type and original header. \`--format json\` prints \`{ sourceId, table, rows, columns: [{ name, type, sourceHeader }], importedAt }\`.
 
+## Your own tables
+
+An agent can keep its own lists in the warehouse across runs, such as keywords, competitors or a lead list, and join them with the client's real data in \`${cli} warehouse query\`.
+
+- \`${cli} tables create keywords --columns "keyword text, volume int, intent text" [--description <text>]\` makes the empty table \`agent_keywords\`. The name is 1 to 48 lowercase letters, digits and underscores. Column types are \`text\`, \`int\`, \`bigint\`, \`numeric\`, \`boolean\`, \`date\`, \`timestamptz\` and \`jsonb\`. Every table also gets \`_row_id\`, \`_created_at\` and \`_created_by\` (\`api_key:<id>\` or \`worker_run:<id>\`).
+- Emails and phone numbers may live only in these tables. Mark the columns that hold them with \`--personal email,phone\`; a column whose name says email, phone or mobile is marked anyway. The Data page never shows a personal column.
+- \`${cli} tables insert keywords --file rows.json\` adds rows from a JSON array of objects keyed by column name, or one object per line in a \`.ndjson\` file. A column a row leaves out is NULL; a column the table lacks is refused. The command sends ${AGENT_TABLE_LIMITS.batchRows.toLocaleString("en-US")} rows or about 4 MB at a time; each batch goes in whole or not at all.
+- \`${cli} tables import keywords --file list.csv [--mode append|replace]\` adds a CSV file's rows, read the way \`${cli} import csv\` reads them, or with \`replace\` swaps them in for every row the table had. Importing into a table that does not exist yet makes it from the file's headers and types; add \`--personal contact\` to mark the columns holding emails or phone numbers, since only a new table takes them. A header the table has no column for is refused.
+- \`${cli} tables delete-rows keywords --where '{"intent": "local"}'\` deletes the rows matching every pair; \`{"_row_id": 12}\` deletes one row. \`${cli} tables drop keywords --yes\` drops the table.
+- \`${cli} tables list\` shows each table with its rows and size. Limits per client: ${AGENT_TABLE_LIMITS.tables} tables, ${AGENT_TABLE_LIMITS.rowsPerTable.toLocaleString("en-US")} rows per table and ${AGENT_TABLE_LIMITS.bytes / (1024 * 1024)} MB in all. A write over a limit is refused with \`413\` and the current size.
+- Over MCP: \`list_tables\`, \`create_table\`, \`insert_rows\` and \`drop_table\`. Over REST: \`GET\`/\`POST /api/v1/tables\`, \`GET\`/\`DELETE /api/v1/tables/<name>\`, \`POST\`/\`DELETE /api/v1/tables/<name>/rows\` and \`POST /api/v1/tables/<name>/import?mode=append|replace\`.
+
+## Finding work emails
+
+\`${cli} enrich email --file people.csv\` finds one verified work email per person. The CSV's header names its columns: \`firstName,lastName,domain,companyName,linkedinUrl\`; each person needs both names and a domain, company name or LinkedIn link. A \`.json\` file is a list of the same objects. It tries LeadMagic, Prospeo, a MillionVerifier guess and Apollo, cheapest first, and stops at the first verified address, so it never pays a second provider for someone already found. A provider the client has no key for is skipped. It prints one row per person: name, domain, email, status (\`valid\`, \`catch_all\` for an unverified address on a domain that accepts every address, \`not_found\`, \`cap_reached\` when a hand's tool limit refused a step, or \`running\` when an earlier call's lookup is still going and the same file should be sent again later), the tool that found it, the cost and the tool runs. \`--steps leadmagic:find-email,prospeo:find-email\` tries only those tools. Sending the same people again replays the lookups already run without paying again. Over MCP: \`find_email\`. Over REST: \`POST /api/v1/enrich/email\` with \`{"people": [...], "steps"?: [...]}\`, up to ${FIND_EMAIL_PEOPLE_MAX} people a request; the CLI sends a longer file in batches of that many.
+
+## Pushing leads to Instantly
+
+\`${cli} outbound push --to instantly:<campaign-id> --csv leads.csv\` loads a lead list into an Instantly campaign without emailing anyone twice. \`--table agent_hosts\` (or an \`import_\` table) pushes a table's rows instead of a file.
+
+- The list needs an \`email\` column. \`first_name\`, \`last_name\`, \`company_name\`, \`website\` and \`phone\` fill Instantly's fields; every other column with a value becomes a custom variable.
+- Skipped before anything is sent: rows without a valid email, repeats in the list, and emails already among the client's synced Instantly leads (any campaign) or added (or found already there) by an earlier push. Instantly then skips anyone already in the campaign or its workspace.
+- Run it with \`--dry-run\` first: it prints the same counts and sends and saves nothing. More rows than \`--max\` (default 5000, at most 50000) is refused, never cut short.
+- Each real push prints an idempotency key; sending the same command again with \`--idempotency-key <key>\` answers the first push instead of pushing again. If the answer says it is still sending, run the same command with the same key again in a few minutes; a push stalled for 10 minutes is resumed where it stopped.
+- It uses the client's stored \`instantly_write\` key (\`${cli} secrets set instantly_write\`), else the Instantly source's key. If Instantly refuses that key, store one that can add leads.
+- Only counts and each email's hash are kept, never the leads. Over MCP: \`push_outbound_leads\`. Over REST: \`POST /api/v1/outbound/pushes\` and \`GET /api/v1/outbound/pushes/<id>\`.
+
 ## Making ads: tools and the creative ledger
 
 1. \`${cli} tools list\` shows each tool id (\`provider:tool\`, such as \`kie:nano-banana\`), whether it runs sync or async, and what it makes. \`--format json\` adds each tool's description, cost, and input JSON Schema.
@@ -181,7 +213,7 @@ Save anything you make before it goes anywhere: an ad written without a tool, an
 
 ### Publishing
 
-\`${cli} content publish <sku> --to <publisher> --target '<json>' --idempotency-key <key>\` publishes an approved item through one of ${brand.name}'s publishers, adding \`--plan <plan-id>\` when it is part of a launch plan and \`--run <run-id>\` from a hand's run. Only the approved version is published; an item edited after approval must be approved again. The server checks every rule first and refuses with each failure listed, recording nothing: one unfinished send per platform account, and at least 15 seconds between sends to one account. Otherwise it records exactly what it sends before sending it, then saves the platform's ids, marks the item launched, and moves the launch plan to live once all its items are out. For Meta without the \`--run\` of a hand in live mode, nothing is sent: the publication is saved as \`not_sent_practice\` with the full request. A send that may or may not have landed stays \`sending\` and is never retried; \`${cli} content reconcile <publication-id>\` asks the platform and finishes it. The same key returns the same publication. A page host is the publisher \`page_host:<host>\` with the target \`{"site":"...","path":"/..."}\`: it puts an approved landing page's HTML online, tags each link that leaves the page with the SKU, and is never held back by practice mode. \`${cli} content show <sku>\` lists the page's deployments with their ids. \`${cli} content unpublish <deployment-id>\` takes one live page down; the site's other pages stay up, and the deployment records when and by whom. It is refused while a synced Meta ad that is delivering links to the page, naming each ad, because a broken link in a running ad wastes money; \`--force\` takes it down anyway. Never roll a site back in Vercel's dashboard instead: the next deploy brings the rolled-away pages back.
+\`${cli} content publish <sku> --to <publisher> --target '<json>' --idempotency-key <key>\` publishes an approved item through one of ${brand.name}'s publishers, adding \`--plan <plan-id>\` when it is part of a launch plan and \`--run <run-id>\` from a hand's run. Only the approved version is published; an item edited after approval must be approved again. The server checks every rule first and refuses with each failure listed, recording nothing: one unfinished send per platform account, and at least 15 seconds between sends to one account. Otherwise it records exactly what it sends before sending it, then saves the platform's ids, marks the item launched, and moves the launch plan to live once all its items are out. For Meta without the \`--run\` of a hand in live mode, nothing is sent: the publication is saved as \`not_sent_practice\` with the full request. A send that may or may not have landed stays \`sending\` and is never retried; \`${cli} content reconcile <publication-id>\` asks the platform and finishes it. The same key returns the same publication. A page host is the publisher \`page_host:<host>\` with the target \`{"site":"...","path":"/..."}\`: it puts an approved landing page's HTML online, tags each link that leaves the page with the SKU, and is never held back by practice mode. \`${cli} content show <sku>\` lists the page's deployments with their ids. \`${cli} content unpublish <deployment-id>\` takes one live page down; the site's other pages stay up, and the deployment records when and by whom. It is refused while a synced Meta ad that is delivering links to the page, naming each ad, because a broken link in a running ad wastes money; \`--force\` takes it down anyway. Never roll a site back in Vercel's dashboard instead: the next deploy brings the rolled-away pages back. An article (\`${cli} content create --kind article --headline "<title>" --html @post.html --file hero.jpg\`) goes to the client's WordPress site with \`${cli} content publish <sku> --to wordpress:<site> --idempotency-key <key>\`, as a draft, or live with \`--status publish\`. Its images are uploaded once per site and each \`<img src>\` naming a \`--file\` points at the uploaded copy. The site's sign-in is saved first with \`${cli} secrets set wordpress:<site> --file wp.json\`, the file holding \`{"baseUrl": "https://...", "username": "...", "applicationPassword": "..."}\` (an application password made in WordPress under Users, Profile).
 
 The \`meta_ads\` publisher puts an approved ad on Facebook, always paused, in an ad set that already exists, \`--to meta_ads --target '{"accountId": "act_<id>", "adsetId": "<id>"}'\`, or in one made with \`${cli} meta adset publish\` (below), \`"adsetPublicationId": "<id>"\` in place of \`adsetId\`. \`"urlTags": "sku"\` (the default) adds the SKU tracking tags to the link; \`"urlTags": "none"\` sends the link exactly as written, Meta macros such as \`{{ad.name}}\` included. The ad needs pictures or a video (not both), body text and an https link in \`fields.link_urls\` (\`fields.cta\`, such as "Shop now", sets the button; \`fields.bodies\`, \`fields.titles\` and \`fields.descriptions\` add variations). The account, the ad set's campaign and the ad set must all be on the hand's publish list, which only an operator sets, and the ad set and campaign must be in the last Meta sync and not archived. A live send also needs a run of the Facebook ads hand, Meta numbers pulled under 12 hours ago, and room under the daily limit of new ads. The ad is named \`<SKU> | <name>\` and its creative's \`url_tags\` carry the SKU. In practice mode the same command stores the full request for review and sends nothing. Each publication's \`targetSnapshot\` names the campaign and ad set as they were at publish time.
 
@@ -342,6 +374,7 @@ ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id
 ${cli} pages brief --step <key> [--funnel <key>] | --page <ref>   the offer, step, current page, best and worst pages of its kind, its ads and how to hand a page back: start here before writing a landing page
 ${cli} pages results [--from <date>] [--to <date>] [--page <ref>]   each landing page's, and each ad and page pair's, real first-touch sales, cost per sale and sales per page view
 ${cli} messages results [--from <date>] [--to <date>] [--channel email|text] [--sequence <id>]   real sales after each follow-up email, text and sequence: every message the buyer clicked or replied to in the ${MESSAGE_CREDIT_DAYS} days before buying (helped), and the latest one (last nudge)
+${cli} seo page-two [--site <site_url>] [--days <n>] [--min-impressions <n>] [--from <n>] [--to <n>] [--by query|query-page] [--limit <n>]   the Google searches where the site sits on page two (average position 11 to 20), from Search Console
 ${cli} winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>] [--ad-format image|video|carousel]   which Facebook ads and landing pages won and flopped in a week or any dates and over 30 days, judged on the client's goal
 ${cli} winners goals | winners goals set <goal> [<goal> ...] | winners goals reset   the goals winners judges this client on, tried in order (sales, sales:triple_whale, booked_calls, meta_results, first_leads), setting them, going back to the default
 ${cli} winners send-to-exodus [--week <date> | --days <n> | --from <date> --to <date>] [--dry-run]   send the winners, with their reasons, lessons and customer words, to Exodus; safe to send again
@@ -362,11 +395,14 @@ ${cli} intake rename <id> <label> | retention <id> <days>
 ${cli} intake delete <id> --yes     delete an address and every event it saved
 ${cli} import csv <file> --table <name>   load a CSV file as the table import_<name>, replacing an earlier import
 ${cli} import remove --table <name> --yes   drop the table import_<name> and its import
+${cli} outbound push --to instantly:<campaign-id> (--csv <file> | --table <name>) [--dry-run] [--max <n>]   load leads into an Instantly campaign, skipping anyone already there or pushed before
 ${cli} tools list                   list generation and research tools
 ${cli} tools run <tool> --input '<json>' [--idempotency-key <key>] [--wait <seconds>]
 ${cli} tools get <run-id>           show a tool run, waiting for it to finish (--wait)
+${cli} tools usage [--month <YYYY-MM>] [--by tool|run]   what tool runs cost in a month, per tool or per scheduled run, split by whose key paid
+${cli} enrich email --file <people.csv | people.json> [--steps <tool,tool>]   find one verified work email per person, cheapest provider first
 ${cli} secrets list                 which provider keys the client has and which key runs use; never the keys themselves
-${cli} secrets set <provider> [--file <path>]   save the client's own provider key from stdin or a file (keys with "Can manage settings")
+${cli} secrets set <provider> [--file <path>]   save the client's own provider key from stdin or a file (keys with "Can manage settings"); wordpress:<site> saves a WordPress site's sign-in
 ${cli} secrets remove <provider>    remove it, so runs use the shared key again
 ${cli} creatives list               list creatives (--status, --kind, --limit)
 ${cli} creatives show <sku>         show one creative with its spec and lineage
@@ -382,6 +418,7 @@ ${cli} content pull <dir> [--kind <kind>] [--platform <p>] [--origin <o>] [--med
 ${cli} content show <sku | item-id> | content edit <sku> [...] --note <why> | content status <sku> <status>
 ${cli} content diff <sku | item-id> [--from <n>] [--to <n>]   what changed between two versions
 ${cli} content publish <sku> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <id>] [--version <n>] [--run <run-id>]   publish an approved item
+${cli} content publish <sku> --to wordpress:<site> [--status publish] --idempotency-key <key>   put an approved article on a WordPress site, as a draft unless --status publish
 ${cli} content reconcile <publication-id>   check whether a publish left sending landed
 ${cli} content unpublish <deployment-id> [--force]   take one deployed landing page down
 ${cli} meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id>]   make a paused Meta ad set to add ads to

package/dist/main.js

@@ -5,12 +5,15 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, META_IDS_MAX, GOOGLE_ADS_IDS_MAX, IMPORT_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
+import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, META_IDS_MAX, GOOGLE_ADS_IDS_MAX, IMPORT_NAME_PATTERN, AGENT_TABLE_LIMITS, AGENT_TABLE_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, OUTBOUND_PUSH_MAX, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
+import { answerRow, batches, ENRICH_EMAIL_USAGE, parsePeople, parseSteps } from "./enrich.js";
 import { META_AD_CREATE_USAGE, metaAdCreateBody } from "./meta-ad.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { scheduleCreateBody, scheduleIdFor, SCHEDULES_CREATE_USAGE } from "./schedules.js";
 import { secretBody, secretProvider, SECRETS_SET_USAGE } from "./secrets.js";
+import { pointImagesAtFiles, publishDestination } from "./articles.js";
+import { dollars, toolUsageReport, toolUsageRequest, TOOLS_USAGE_USAGE } from "./tool-usage.js";
 import { guide, skill } from "./guide.js";
 import { PULL_STATE_FILE, pullContent } from "./pull.js";
 import { AGENTS_MD_MARKER, metaAdsAgentsMd, PLAYBOOK_CHOICES, playbooks } from "./playbooks.js";
@@ -23,6 +26,9 @@ const META_CHANGE_COLUMNS = ["id", "level", "object", "change", "status", "when"
 const GOOGLE_ADS_CHANGE_COLUMNS = ["id", "account", "level", "object", "change", "status", "when", "by", "reason"];
 const SERVER_WAIT_CAP = 50;
 const VOICE_USAGE = "voice [--kind opener|objection|pain|desire|phrase] [--since <YYYY-MM-DD>] [--sort common|useful] [--limit <n>] [--json]";
+const CONTENT_PUBLISH_USAGE = "content publish <sku | item-id> (--to <publisher> --target '<json>' | --to wordpress:<site> [--status draft|publish]) --idempotency-key <key> [--plan <plan-id>] [--version <n>] [--run <run-id>]";
+const META_MOVE_USAGE = 'meta ads move <ad-id> --to-adset <adset-id> --reason "<why>" [--keep-original] [--status active|paused] [--run <run-id>] [--idempotency-key <key>]';
+const OUTBOUND_PUSH_USAGE = `outbound push --to instantly:<campaign-id> (--csv <file> | --table <import_ or agent_ table>) [--dry-run] [--max <n>] [--idempotency-key <key>]`;
 const commands = {
     login: {
         usage: `login [--client <name>]   (paste the key when asked, pipe it on stdin, or set ${envPrefix}_API_KEY); --client saves it under that client's name`,
@@ -274,6 +280,45 @@ const commands = {
             printRun(await waitForRun(connection, run, options.wait), options.format);
         },
     },
+    "enrich email": {
+        usage: ENRICH_EMAIL_USAGE,
+        async run(args, options) {
+            if (args.length > 0 || !options.file)
+                throw new CliError(`Usage: ${ENRICH_EMAIL_USAGE}`, exitCodes.usage);
+            const people = parsePeople(await readFile(await inRunFolder(options.file), "utf8"), options.file);
+            const steps = parseSteps(options.steps);
+            const connection = await resolveConnection(options);
+            const answers = [];
+            for (const batch of batches(people)) {
+                const { people: found } = await api(connection, "/api/v1/enrich/email", { people: batch, ...(steps ? { steps } : {}) });
+                answers.push(...found);
+            }
+            if (options.format === "json")
+                return printJson({ people: answers });
+            console.log(renderTable(["name", "domain", "email", "status", "found by", "cost", "run ids"], answers.map(answerRow)));
+            for (const answer of answers) {
+                for (const step of answer.steps) {
+                    if (step.reason && (step.status === "failed" || step.status === "refused" || step.status === "running"))
+                        console.log(`${answerRow(answer).name}: ${step.tool} ${step.status}: ${step.reason}`);
+                }
+            }
+        },
+    },
+    "tools usage": {
+        usage: TOOLS_USAGE_USAGE,
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError(`Usage: ${TOOLS_USAGE_USAGE}`, exitCodes.usage);
+            const { path, by } = toolUsageRequest(options);
+            const { toolUsage } = await api(await resolveConnection(options), path);
+            if (options.format === "json")
+                return printJson({ toolUsage });
+            const report = toolUsageReport(toolUsage, by);
+            console.log(report.title);
+            console.log(report.rows.length === 0 ? "No tool runs." : renderTable(report.columns, report.rows));
+            console.log(`\n${report.footer.join("\n")}`);
+        },
+    },
     "sources list": {
         usage: "sources list",
         async run(args, options) {
@@ -405,6 +450,9 @@ const commands = {
             const { secret } = await api(connection, secretPath(provider), secretBody(text), "PUT");
             if (options.format === "json")
                 return printJson({ secret });
+            if (secret.provider.startsWith("wordpress:")) {
+                return console.log(`Saved the sign-in for the WordPress site ${secret.provider.slice("wordpress:".length)}. content publish --to ${secret.provider} uses it.`);
+            }
             console.log(`Saved the client's own ${secret.provider} key. Its ${secret.provider} runs now use it instead of the shared one.`);
         },
     },
@@ -540,13 +588,37 @@ const commands = {
             const name = importName(options.table);
             const file = await readImportFile(args[0]);
             const connection = await resolveConnection(options);
-            const result = await uploadCsv(connection, name, file);
+            const result = await uploadCsv(connection, `/api/v1/imports/csv?table=${encodeURIComponent(name)}`, file);
             if (options.format === "json")
                 return printJson(result);
             console.log(`Imported ${result.rows} ${result.rows === 1 ? "row" : "rows"} into ${result.table}.`);
             console.log(renderTable(["column", "type", "header"], result.columns.map((c) => ({ column: c.name, type: c.type, header: c.sourceHeader }))));
         },
     },
+    "outbound push": {
+        usage: OUTBOUND_PUSH_USAGE,
+        async run(args, options) {
+            if (args.length !== 0 || !options.to || (options.csv === undefined) === (options.table === undefined))
+                throw new CliError(`Usage: ${OUTBOUND_PUSH_USAGE}`, exitCodes.usage);
+            const max = options.max === undefined ? OUTBOUND_PUSH_MAX.default : Number(options.max);
+            if (!Number.isInteger(max) || max < 1 || max > OUTBOUND_PUSH_MAX.ceiling) {
+                throw new CliError(`--max must be a whole number from 1 to ${OUTBOUND_PUSH_MAX.ceiling}.`, exitCodes.usage);
+            }
+            const csv = options.csv === undefined ? undefined : await readOutboundCsv(options.csv);
+            const idempotencyKey = options.dryRun ? options.idempotencyKey : announceKey(options.idempotencyKey ?? randomUUID());
+            const body = { to: options.to, csv, table: options.table, max, dryRun: options.dryRun, idempotencyKey };
+            const { push } = await api(await resolveConnection(options), "/api/v1/outbound/pushes", body);
+            if (options.format === "json")
+                printJson({ push });
+            else
+                process.stdout.write(outboundPushText(push));
+            if (push.status === "running") {
+                throw new CliError(`This push is still sending. Run the same command again with --idempotency-key ${push.idempotencyKey} in a few minutes.`, exitCodes.error);
+            }
+            if (push.status === "failed" || push.status === "partial")
+                throw new CliError(push.error ?? `The push ${push.status === "failed" ? "failed" : "was only partly sent"}.`, exitCodes.error);
+        },
+    },
     "import remove": {
         usage: "import remove --table <name> --yes",
         async run(args, options) {
@@ -564,6 +636,112 @@ const commands = {
             console.log(`Removed ${result.table} and its rows.`);
         },
     },
+    "tables list": {
+        usage: "tables list",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: tables list", exitCodes.usage);
+            const list = await api(await resolveConnection(options), TABLES_PATH);
+            if (options.format === "json")
+                return printJson(list);
+            if (list.tables.length === 0)
+                console.log("No agent tables yet. Make one with tables create.");
+            else
+                console.log(renderTable(["table", "rows", "size", "columns", "description"], list.tables.map(tableRow)));
+            console.log(`${list.usage.tables} of ${list.limits.tables} tables, ${megabytes(list.usage.bytes)} of ${list.limits.bytes / (1024 * 1024)} MB. Personal columns, marked *, hold emails or phone numbers.`);
+        },
+    },
+    "tables create": {
+        usage: 'tables create <name> --columns "<name type, ...>" [--personal <col,col>] [--description <text>]',
+        async run(args, options) {
+            const usage = 'Usage: tables create <name> --columns "keyword text, volume int" [--personal email,phone] [--description <text>]';
+            if (args.length !== 1 || !options.columns)
+                throw new CliError(usage, exitCodes.usage);
+            const personal = (options.personal ?? "").split(",").map((p) => p.trim()).filter((p) => p !== "");
+            const body = { name: agentTableName(args[0]), columns: options.columns, personal, description: options.description };
+            const { table } = await api(await resolveConnection(options), TABLES_PATH, body);
+            if (options.format === "json")
+                return printJson({ table });
+            console.log(`Made ${table.table}. Query it with warehouse query, add rows with tables insert or tables import.`);
+            console.log(renderTable(["column", "type", "personal"], table.columns.map((c) => ({ column: c.name, type: c.type, personal: c.personal ? "yes" : "" }))));
+        },
+    },
+    "tables insert": {
+        usage: "tables insert <name> --file <rows.json | rows.ndjson>",
+        async run(args, options) {
+            if (args.length !== 1 || !options.file)
+                throw new CliError("Usage: tables insert <name> --file <rows.json | rows.ndjson>", exitCodes.usage);
+            const name = agentTableName(args[0]);
+            const rows = await readRowsFile(options.file);
+            const connection = await resolveConnection(options);
+            let inserted = 0;
+            let last = null;
+            const batches = rowBatches(rows);
+            for (const batch of batches) {
+                try {
+                    last = await api(connection, `${tablePath(name)}/rows`, batch);
+                }
+                catch (error) {
+                    if (inserted === 0 || !(error instanceof CliError))
+                        throw error;
+                    throw new CliError(`${inserted} rows went in, in earlier batches, before this one was refused: ${error.message}`, error.exitCode);
+                }
+                inserted += last.inserted;
+            }
+            const result = { table: last.table, inserted, batches: batches.length, rows: last.rows, bytes: last.bytes };
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Added ${rowCount(inserted)} to ${result.table}${batches.length > 1 ? ` in ${batches.length} batches` : ""}. It now has ${rowCount(result.rows)}.`);
+        },
+    },
+    "tables import": {
+        usage: "tables import <name> --file <file.csv> [--mode append|replace] [--personal <col,col>]",
+        async run(args, options) {
+            const usage = "Usage: tables import <name> --file <file.csv> [--mode append|replace] [--personal email,phone]";
+            if (args.length !== 1 || !options.file)
+                throw new CliError(usage, exitCodes.usage);
+            const mode = options.mode ?? "append";
+            if (mode !== "append" && mode !== "replace")
+                throw new CliError("--mode must be append or replace.", exitCodes.usage);
+            const name = agentTableName(args[0]);
+            const personal = options.personal ? `&personal=${encodeURIComponent(options.personal)}` : "";
+            const file = await readImportFile(options.file);
+            const result = await uploadCsv(await resolveConnection(options), `${tablePath(name)}/import?mode=${mode}${personal}`, file);
+            if (options.format === "json")
+                return printJson(result);
+            const verb = result.created ? "Made" : mode === "replace" ? "Replaced the rows of" : "Added to";
+            console.log(`${verb} ${result.table}: ${rowCount(result.inserted)} from the file. It now has ${rowCount(result.rows)}.`);
+            if (result.created)
+                console.log(renderTable(["column", "type", "personal"], result.columns.map((c) => ({ column: c.name, type: c.type, personal: c.personal ? "yes" : "" }))));
+        },
+    },
+    "tables delete-rows": {
+        usage: "tables delete-rows <name> --where '<json>' | @file.json",
+        async run(args, options) {
+            const usage = `Usage: tables delete-rows <name> --where '{"column": "value"}'`;
+            if (args.length !== 1 || !options.where)
+                throw new CliError(usage, exitCodes.usage);
+            const where = await parseJson(options.where, "--where");
+            const result = await api(await resolveConnection(options), `${tablePath(agentTableName(args[0]))}/rows`, { where }, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Deleted ${rowCount(result.deleted)} from ${result.table}. It now has ${rowCount(result.rows)}.`);
+        },
+    },
+    "tables drop": {
+        usage: "tables drop <name> --yes",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: tables drop <name> --yes", exitCodes.usage);
+            const name = agentTableName(args[0]);
+            if (!options.yes)
+                throw new CliError(`This drops the table agent_${name} and all its rows. Add --yes to confirm: tables drop ${name} --yes`, exitCodes.usage);
+            const result = await api(await resolveConnection(options), tablePath(name), undefined, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Dropped ${result.table} and its rows.`);
+        },
+    },
     "creatives list": {
         usage: "creatives list [--status <status>] [--kind static|video|copy] [--limit <n>]",
         async run(_args, options) {
@@ -685,11 +863,11 @@ const commands = {
         usage: "content create --kind <kind> [--name <name>] [--subject <s>] [--preview <s>] [--headline <s>] [--body <text> | @file] [--html @file] [--fields '<json>' | @file.json] [--file <path> ...] [--tool-run <id> ...] [--run <agent-run-id>] [--note <why>] [--plan <plan-id> [--role <role>]]",
         async run(args, options) {
             if (args.length > 0 || !options.kind)
-                throw new CliError("Usage: content create --kind ad|email|sms|landing_page|video|social_post [...]", exitCodes.usage);
+                throw new CliError("Usage: content create --kind ad|email|sms|landing_page|video|social_post|article [...]", exitCodes.usage);
             const connection = await resolveConnection(options);
             const content = await api(connection, "/api/v1/content", {
                 kind: options.kind,
-                ...(await contentInput(options, connection)),
+                ...(await contentInput(options, connection, async () => options.kind)),
                 ...(options.plan === undefined ? {} : { launchPlanId: options.plan }),
                 ...(options.role === undefined ? {} : { launchPlanRole: options.role }),
             });
@@ -707,7 +885,7 @@ const commands = {
             const connection = await resolveConnection(options);
             const content = await api(connection, "/api/v1/content/captures", {
                 kind: options.kind,
-                ...(await contentInput(options, connection)),
+                ...(await contentInput(options, connection, async () => options.kind)),
                 transcript: options.transcript === undefined ? undefined : { text: await textOrFile(options.transcript), language: options.language },
                 source: options.source,
                 url: options.url,
@@ -776,6 +954,22 @@ const commands = {
             printMessageResults(results);
         },
     },
+    "seo page-two": {
+        usage: "seo page-two [--site <site_url>] [--days <n>] [--min-impressions <n>] [--from <position>] [--to <position>] [--by query|query-page] [--limit <n>]   (the Google searches where the site sits around positions 11 to 20, from Search Console)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: seo page-two [--site <site_url>] [--days <n>] [--min-impressions <n>] [--from <position>] [--to <position>] [--by query|query-page] [--limit <n>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            const asked = { site: options.site, days: options.days, minImpressions: options.minImpressions, from: options.from, to: options.to, by: options.by, limit: options.limit };
+            for (const [name, value] of Object.entries(asked))
+                if (value !== undefined)
+                    query.set(name, value);
+            const report = await api(await resolveConnection(options), `/api/v1/seo/page-two${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson(report);
+            printPageTwo(report);
+        },
+    },
     winners: {
         usage: "winners [--week <YYYY-MM-DD> | --days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--top <n>] [--ad-format image|video|carousel]   (which Facebook ads and landing pages won and flopped, judged on each client's goal; see winners goals)",
         async run(args, options) {
@@ -918,7 +1112,7 @@ const commands = {
             if (args.length !== 1)
                 throw new CliError("Usage: content edit <sku | item-id> [--body <text> | @file] [--note <why>] [...]", exitCodes.usage);
             const connection = await resolveConnection(options);
-            const input = await contentInput(options, connection);
+            const input = await contentInput(options, connection, async () => (await api(connection, `/api/v1/content/${encodeURIComponent(args[0])}`)).item.kind);
             if (Object.keys(input).every((k) => k === "runId" || k === "note")) {
                 throw new CliError("content edit needs something to change, such as --body, --subject or --file.", exitCodes.usage);
             }
@@ -941,17 +1135,19 @@ const commands = {
         },
     },
     "content publish": {
-        usage: "content publish <sku | item-id> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <plan-id>] [--version <n>] [--run <run-id>]",
+        usage: CONTENT_PUBLISH_USAGE,
         async run(args, options) {
-            if (args.length !== 1 || !options.to || options.target === undefined || !options.idempotencyKey) {
-                throw new CliError("Usage: content publish <sku | item-id> --to <publisher> --target '<json>' --idempotency-key <key> [--plan <plan-id>] [--version <n>] [--run <run-id>]", exitCodes.usage);
-            }
+            if (args.length !== 1 || !options.to || !options.idempotencyKey)
+                throw new CliError(`Usage: ${CONTENT_PUBLISH_USAGE}`, exitCodes.usage);
             const version = options.version === undefined ? undefined : Number(options.version);
             if (version !== undefined && !(Number.isInteger(version) && version >= 1))
                 throw new CliError("--version must be a whole number from 1.", exitCodes.usage);
+            const destination = publishDestination(options.to, {
+                target: options.target === undefined ? undefined : await parseJson(options.target, "--target"),
+                status: options.status,
+            });
             const { publication } = await api(await resolveConnection(options), `/api/v1/content/${encodeURIComponent(args[0])}/publish`, {
-                publisher: options.to,
-                target: await parseJson(options.target, "--target"),
+                ...destination,
                 idempotencyKey: options.idempotencyKey,
                 ...(options.plan === undefined ? {} : { launchPlanId: options.plan }),
                 ...(version === undefined ? {} : { version }),
@@ -1032,8 +1228,36 @@ const commands = {
     "meta adset resume": metaStatusCommand("adset", "resume"),
     "meta adset budget": metaBudgetCommand("adset"),
     "meta campaign budget": metaBudgetCommand("campaign"),
+    "meta ads move": {
+        usage: `${META_MOVE_USAGE}   copy an ad into another ad set in its account and pause the original`,
+        async run(args, options) {
+            if (args.length !== 1 || !options.toAdset || !options.reason)
+                throw new CliError(`Usage: ${META_MOVE_USAGE}`, exitCodes.usage);
+            if (options.status !== undefined && options.status !== "active" && options.status !== "paused") {
+                throw new CliError("--status must be active or paused: how the copy starts.", exitCodes.usage);
+            }
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`move-${randomUUID()}`);
+            const change = await api(await resolveConnection(options), "/api/v1/meta/changes", {
+                kind: "move",
+                adId: args[0],
+                toAdsetId: options.toAdset,
+                status: options.status ?? "paused",
+                keepOriginal: options.keepOriginal,
+                reason: options.reason,
+                idempotencyKey,
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            if (options.format === "json")
+                return printJson(change);
+            printMetaChangeResult({ changes: [change], unchanged: [] }, options.format);
+            if (change.kind === "move" && change.status === "applied") {
+                const original = change.after.keepOriginal ? "was left as it was" : "is paused";
+                console.log(`Ad ${change.objectId} was copied to ad set ${change.after.adsetId} as ad ${change.after.copyId} (${change.after.copyStatus.toLowerCase()}); the original ${original}.`);
+            }
+        },
+    },
     "meta changes": {
-        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off and budgets changed, newest first",
+        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off, budgets changed and ads moved, newest first",
         async run(args, options) {
             if (args.length !== 0)
                 throw new CliError("Usage: meta changes [--since <YYYY-MM-DD>]", exitCodes.usage);
@@ -2658,6 +2882,18 @@ function pageNumbers(r) {
         "sales/view": r.salesPerLandingPageView,
     };
 }
+function printPageTwo(report) {
+    if (report.missing !== null)
+        return console.log(report.missing);
+    const { positions, minImpressions, dates } = report;
+    const asked = `at average position ${positions.from} to ${positions.to}, shown at least ${minImpressions} times, ${dates.from} to ${dates.to}`;
+    if (report.keywords.length === 0)
+        return console.log(`No searches ${asked}.`);
+    console.log(`Searches ${asked}, most impressions first:`);
+    const pageColumn = report.by === "query" ? "top page" : "page";
+    const rows = report.keywords.map((k) => ({ site: k.siteUrl, query: k.query, [pageColumn]: k.page, impressions: k.impressions, clicks: k.clicks, ctr: k.ctr, position: k.position }));
+    console.log(renderTable(["site", "query", pageColumn, "impressions", "clicks", "ctr", "position"], rows));
+}
 function printPageResults(results) {
     if (results.pages.length === 0)
         return console.log(`No page results from ${results.from} to ${results.to}.`);
@@ -2937,7 +3173,10 @@ Options:
   --retention-days <n>  how many days intake create keeps each event (default: 90)
   --signing-key-stdin   read the sender's signing key for intake create or intake signing-key from stdin (mailgun needs one)
   --table <name>        the table import csv loads the file into, or import remove drops, as import_<name>;
-                        for warehouse schema, a table to describe in full; repeat for several
+                        for warehouse schema, a table to describe in full; repeat for several;
+                        for outbound push, the import_ or agent_ table holding the leads
+  --csv <file>          outbound push: the leads as a CSV file with an email column, up to 4 MB
+  --max <n>             outbound push: refuse more rows than this (default 5000, at most 50000)
   --summary             warehouse schema: one short row per table (kind, source, column count, summary)
   --search <words>      warehouse schema: describe in full the tables whose name, description or columns mention a word
   --out <path>          the file, or existing folder, creatives download, media download and warehouse query save to; warehouse query
@@ -2948,11 +3187,24 @@ Options:
   --media               with content pull, also save each item's files and HTML under media/ in the folder
   --full                with content pull, fetch every item, not only what changed since the last pull (brings new numbers)
   --force               content unpublish: take the page down even while delivering Meta ads link to it
+  --to-adset <id>       meta ads move: the ad set to copy the ad into, in the same ad account
+  --keep-original       meta ads move: leave the original ad as it is instead of pausing it
   --plan <json>         meta adset publish: the ad set to make, {"kind": "copy", ...} or {"kind": "create", ...}
-  --yes                 confirm intake delete or import remove, which delete saved data for good
+  --columns <list>      tables create: the columns as "name type" pairs, such as "keyword text, volume int"; types are
+                        text, int, bigint, numeric, boolean, date, timestamptz and jsonb
+  --personal <list>     tables create and tables import into a new table: the columns holding emails or phone numbers,
+                        such as email,phone; the Data page never shows them (a column named for an email, phone or
+                        mobile is personal anyway)
+  --description <text>  tables create: what the table holds, which warehouse schema shows
+  --where <json | @file.json>   tables delete-rows: {column: value} pairs a row must all match to be deleted
+  --mode append|replace tables import: add the file's rows (default) or replace every row the table has
+  --yes                 confirm intake delete, import remove or tables drop, which delete saved data for good
   --from <YYYY-MM-DD>   first day funnel, campaigns, money, brief, pages results and messages results cover (default: 29 days before --to)
-  --to <YYYY-MM-DD>     last day funnel, campaigns, money, brief, pages results and messages results cover (default: today in the workspace reporting time zone)
+  --to <YYYY-MM-DD>     last day funnel, campaigns, money, brief, pages results and messages results cover (default: today in the workspace reporting time zone);
+                        for outbound push, where the leads go: instantly:<campaign-id>
   --grain <grain>       how funnel and money group days: day (default), week (starting Monday) or month
+  --month <YYYY-MM>     the month tools usage covers, in the workspace reporting time zone (default: this month)
+  --by tool|run         tools usage: one row per tool (default) or per scheduled hand run
   --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
                         for content track-link, where the link goes: facebook, email, sms or web (default);
                         with messages results, email or text
@@ -2961,9 +3213,14 @@ Options:
   --top <n>             how many best ads, worst ads, pages and campaigns brief shows, or ads in each winners list (default: 5, at most 20)
   --week <YYYY-MM-DD>   any day of the week winners covers, Monday to Sunday (default: the latest complete week)
   --days <n>            winners: the last n complete days, ending yesterday, instead of a week (at most 90); or give winners
-                        --from and --to for any dates
+                        --from and --to for any dates; seo page-two: how many days, ending on Search Console's newest day (default: 90)
+  --site <site_url>     seo page-two: only this Search Console property, such as sc-domain:example.com
+  --min-impressions <n> seo page-two: only searches shown at least n times (default: 100)
+  --from, --to <n>      seo page-two: the average positions kept, both included (default: 11 to 20)
+  --by query|query-page seo page-two: one row per search, with its top page (default), or one per search and page
   --body, --html <text | @file>   the words, or the full HTML, content create, capture and edit save
-  --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several; for secrets set, the file holding the key
+  --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several; for secrets set, the file holding the key;
+                        for enrich email, the people: a CSV (firstName,lastName,domain,companyName,linkedinUrl) or a JSON list
   --transcript <text | @file>   what is said in the first video or audio file content capture saves, so none is paid for
   --language <code>     the spoken language of --transcript, such as en
   --source <text>       where the content content capture saves came from, in words
@@ -2971,7 +3228,7 @@ Options:
   --tool-run <id>       a succeeded tool run content create and edit link; repeat for several
   --run <id>            the agent run making the content (content) or the Meta change (meta ads|adset), the tool run to
                         record (creatives create), or the tool run whose outputs media list shows
-  --reason <why>        why: what meta ads|adset pause|resume, meta adset|campaign budget, meta changes undo, meta ad create --status active and
+  --reason <why>        why: what meta ads|adset pause|resume, meta ads move, meta adset|campaign budget, meta changes undo, meta ad create --status active and
                         the google-ads commands record in the change log
   --percent <n>         with meta adset|campaign budget or google-ads campaign budget, the whole-number percent change from the daily budget now (--percent=-10 lowers it)
   --daily <n>           with meta adset|campaign budget, the new daily budget in the currency's smallest unit (6000 is 60.00 USD); with
@@ -3009,6 +3266,7 @@ Options:
                         --step is in, when two funnels have a step with that key
   --step <key>          with plans create, the step of --funnel this push itself is, as on the confirmed map;
                         with pages brief, the step whose page the brief is for
+  --steps <a,b>         with enrich email, the email tools to try (default: all four); they still run cheapest first
   --page <ref>          with pages brief, the page to make a new version of: its address, page key, item id or SKU;
                         with pages results, the one page to show: its address, page key or item id
   --harness <list>      which agents skill publish marks the skill for: claude, codex, or claude,codex (default)
@@ -3019,9 +3277,9 @@ Options:
   --from, --to <n>      with content diff, the two versions to compare (default: the one before the current one, and the current one)
   --sort <column>       how content search sorts: recent (default) or a content_scorecard number, such as click_rate or roas
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
-  --limit <n>           how many results content search, creatives list, media list, campaigns, voice, ads tags, content tags
-                        and content to-check return, how many ads ads autotag tags and how many items content autotag
-                        tags, or how many ads each ads tag-formats batch looks at (default 2000)
+  --limit <n>           how many results content search, creatives list, media list, campaigns, voice, ads tags, content tags,
+                        content to-check and seo page-two return, how many ads ads autotag tags and how many items content autotag
+                        tags, or how many ads each ads tag-formats batch looks at (default 2000; seo page-two: 50)
   --library <slug>      with knowledge search, only this library: creative-cartel, exodus or meta-policy
   --angle, --hook-kind, --ad-format, --awareness <value>   with knowledge search, only library entries tagged that way, and
                         your own ads tagged the same way with their results; with knowledge tag, the tags to put on an entry;
@@ -3073,6 +3331,8 @@ function parseOptions(argv) {
             project: { type: "boolean", default: false },
             input: { type: "string" },
             "idempotency-key": { type: "string" },
+            csv: { type: "string" },
+            max: { type: "string" },
             wait: { type: "string", default: String(DEFAULT_WAIT_SECONDS) },
             status: { type: "string" },
             kind: { type: "string" },
@@ -3090,6 +3350,10 @@ function parseOptions(argv) {
             "retention-days": { type: "string" },
             "signing-key-stdin": { type: "boolean", default: false },
             table: { type: "string", multiple: true },
+            columns: { type: "string" },
+            personal: { type: "string" },
+            description: { type: "string" },
+            where: { type: "string" },
             summary: { type: "boolean", default: false },
             search: { type: "string" },
             out: { type: "string" },
@@ -3099,6 +3363,8 @@ function parseOptions(argv) {
             full: { type: "boolean", default: false },
             force: { type: "boolean", default: false },
             yes: { type: "boolean", default: false },
+            "to-adset": { type: "string" },
+            "keep-original": { type: "boolean", default: false },
             from: { type: "string" },
             since: { type: "string" },
             until: { type: "string" },
@@ -3107,6 +3373,8 @@ function parseOptions(argv) {
             cursor: { type: "string" },
             to: { type: "string" },
             grain: { type: "string" },
+            month: { type: "string" },
+            by: { type: "string" },
             channel: { type: "string" },
             campaign: { type: "string" },
             account: { type: "string" },
@@ -3116,6 +3384,8 @@ function parseOptions(argv) {
             top: { type: "string" },
             week: { type: "string" },
             days: { type: "string" },
+            site: { type: "string" },
+            "min-impressions": { type: "string" },
             name: { type: "string" },
             subject: { type: "string" },
             preview: { type: "string" },
@@ -3158,6 +3428,7 @@ function parseOptions(argv) {
             diff: { type: "string" },
             funnel: { type: "string" },
             step: { type: "string" },
+            steps: { type: "string" },
             page: { type: "string" },
             sequence: { type: "string" },
             workspace: { type: "string" },
@@ -3205,6 +3476,8 @@ function parseOptions(argv) {
             project: values.project,
             input: values.input,
             idempotencyKey: values["idempotency-key"],
+            csv: values.csv,
+            max: values.max,
             wait,
             status: values.status,
             kind: values.kind,
@@ -3223,6 +3496,10 @@ function parseOptions(argv) {
             signingKeyStdin: values["signing-key-stdin"],
             table: values.table?.at(-1),
             tables: values.table ?? [],
+            columns: values.columns,
+            personal: values.personal,
+            description: values.description,
+            where: values.where,
             summary: values.summary,
             search: values.search,
             out: values.out,
@@ -3232,6 +3509,8 @@ function parseOptions(argv) {
             full: values.full,
             force: values.force,
             yes: values.yes,
+            toAdset: values["to-adset"],
+            keepOriginal: values["keep-original"],
             from: values.from,
             since: values.since,
             until: values.until,
@@ -3240,6 +3519,8 @@ function parseOptions(argv) {
             cursor: values.cursor,
             to: values.to,
             grain: values.grain,
+            month: values.month,
+            by: values.by,
             channel: values.channel,
             campaign: values.campaign,
             account: values.account,
@@ -3249,6 +3530,8 @@ function parseOptions(argv) {
             top: values.top,
             week: values.week,
             days: values.days,
+            site: values.site,
+            minImpressions: values["min-impressions"],
             name: values.name,
             subject: values.subject,
             preview: values.preview,
@@ -3291,6 +3574,7 @@ function parseOptions(argv) {
             diff: values.diff,
             funnel: values.funnel,
             step: values.step,
+            steps: values.steps,
             page: values.page,
             sequence: values.sequence,
             workspace: values.workspace,
@@ -3494,9 +3778,12 @@ const INLINE_CONTENT_BYTES = 3 * 1024 * 1024;
  * The request body the content create and edit flags describe; flags not given are left out. Files go base64 while
  * they and the HTML fit in one request; any other file goes to storage first and is named by its upload id.
  */
-async function contentInput(options, connection) {
-    const html = options.html === undefined ? undefined : await textOrFile(options.html);
-    const files = await sendableFiles(await readContentFiles(options.files), connection, html === undefined ? 0 : Buffer.byteLength(html));
+async function contentInput(options, connection, kindOf) {
+    const read = await readContentFiles(options.files);
+    const given = options.html === undefined ? undefined : await textOrFile(options.html);
+    // Only an article's publisher swaps sha256: sources for uploaded files; any other kind keeps its HTML as written.
+    const html = given !== undefined && read.length > 0 && (await kindOf()) === "article" ? pointImagesAtFiles(given, read) : given;
+    const files = await sendableFiles(read, connection, html === undefined ? 0 : Buffer.byteLength(html));
     const input = {
         name: options.name,
         subject: options.subject,
@@ -3524,7 +3811,7 @@ async function readContentFiles(paths) {
         const contentType = FILE_TYPES[extname(path).toLowerCase()];
         if (!contentType)
             throw new CliError(`${path}: --file takes ${Object.keys(FILE_TYPES).join(", ")} files.`, exitCodes.usage);
-        read.push({ contentType, data: await readFile(await inRunFolder(path)) });
+        read.push({ path, contentType, data: await readFile(await inRunFolder(path)) });
     }
     return read;
 }
@@ -3662,7 +3949,6 @@ function printPlan(plan, format) {
     console.log(renderTable(["position", "sku", "kind", "role", "status", "name"], plan.items));
 }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
 /** The workspace's scheduled hand for the skill named `ref`, else the one whose id it is: a skill's name may look like a uuid. */
 async function workerId(connection, ref) {
     const { workers } = await api(connection, "/api/v1/workers");
@@ -3816,18 +4102,65 @@ function metaBudgetCommand(level) {
         },
     };
 }
+function metaChangeWords(c) {
+    switch (c.kind) {
+        case "status":
+            return `${c.before.status} -> ${c.after.status}`;
+        case "budget":
+            return `daily budget ${c.before.dailyBudget} -> ${c.after.dailyBudget}`;
+        case "move":
+            return `move to ad set ${c.after.adsetId}, copy ${c.after.copyId ?? "not known yet"} (${c.after.copyStatus})${c.after.keepOriginal ? ", original kept" : ", original paused"}`;
+        case "move_undo":
+            return `undo move: copy ${c.after.copyId} paused, original back to ${c.after.originalStatus}`;
+    }
+}
 function metaChangeRow(c) {
     return {
         id: c.id,
         level: c.level,
         object: c.objectId,
-        change: c.kind === "budget" ? `daily budget ${c.before.dailyBudget} -> ${c.after.dailyBudget}` : `${c.before.status} -> ${c.after.status}`,
+        change: metaChangeWords(c),
         status: c.undoneBy ? `${c.status} (undone by ${c.undoneBy})` : c.error ? `${c.status}: ${c.error}` : c.status,
         when: c.createdAt,
         by: c.requestedBy,
         reason: excerpt(c.reason, 60),
     };
 }
+async function readOutboundCsv(path) {
+    const file = await readImportFile(path);
+    if (file.byteLength > OUTBOUND_PUSH_MAX.csvBytes) {
+        throw new CliError(`${path} is ${megabytes(file.byteLength)} MB. A push takes a CSV of at most ${OUTBOUND_PUSH_MAX.csvBytes / (1024 * 1024)} MB. Load it with \`${brand.slug} import csv\` first, then push with --table import_<name>.`, exitCodes.usage);
+    }
+    return file.toString("utf8");
+}
+function outboundPushText(push) {
+    const c = push.counts;
+    const where = `Instantly campaign ${push.campaignId}`;
+    const lines = [
+        push.dryRun
+            ? `Dry run: ${c.toSend} of ${c.received} ${c.received === 1 ? "row" : "rows"} would go to ${where}. Nothing was sent or saved.`
+            : `Pushed to ${where}: ${c.added} added, ${c.skippedRemote} already in Instantly, ${c.failed} failed (${push.status}).`,
+        renderTable(["rows", "count"], [
+            { rows: "received", count: String(c.received) },
+            { rows: "invalid email", count: String(c.invalid) },
+            { rows: "repeated in the list", count: String(c.duplicate) },
+            { rows: "already sent or synced", count: String(c.duplicateLocal) },
+            { rows: push.dryRun ? "would send" : "sent", count: String(c.toSend) },
+            ...(push.dryRun
+                ? []
+                : [
+                    { rows: "skipped by Instantly", count: String(c.skippedRemote) },
+                    { rows: "added", count: String(c.added) },
+                    { rows: "failed", count: String(c.failed) },
+                ]),
+        ]),
+    ];
+    if (push.keySource)
+        lines.push(`Key: ${push.keySource === "instantly_write" ? "the stored instantly_write key" : "the Instantly source's key"}.`);
+    if (push.id)
+        lines.push(`Push id: ${push.id}`);
+    return `${lines.join("\n")}\n`;
+}
 /** Told on stderr before the request goes out, so a request whose answer is lost can be sent again with the same key. */
 function announceKey(key) {
     console.error(`Idempotency key: ${key} (if no answer comes, send the same command again with --idempotency-key ${key})`);
@@ -3971,8 +4304,9 @@ function printRun(run, format) {
 const HOSTED_UPLOAD_MB = 4.5;
 const megabytes = (bytes) => Math.round((bytes / (1024 * 1024)) * 10) / 10;
 /** A file over the hosted app's request limit goes to storage first, and the server imports it from there. */
-async function uploadCsv(connection, name, file) {
-    const table = `/api/v1/imports/csv?table=${encodeURIComponent(name)}`;
+/** Sends a CSV file to an import route, `route` with its query string, through file storage first when it is too big for one request. */
+async function uploadCsv(connection, route, file) {
+    const table = route;
     if (file.byteLength > HOSTED_UPLOAD_MB * 1024 * 1024) {
         const upload = await api(connection, "/api/v1/imports/csv/uploads", {}).catch((error) => {
             // A server without storage takes the file directly, which works for anything its host lets through.
@@ -3989,13 +4323,75 @@ async function uploadCsv(connection, name, file) {
         return await apiUpload(connection, table, file, "text/csv");
     }
     catch (error) {
-        // The importer's own 413 is too_large; any other 413 is the hosting platform refusing the body before the app sees it.
-        if (error instanceof ApiError && error.status === 413 && error.code !== "too_large") {
+        // A 413 without an error code is the hosting platform refusing the body before the app sees it.
+        if (error instanceof ApiError && error.status === 413 && error.code === undefined) {
             throw new CliError(`The server accepts at most ${HOSTED_UPLOAD_MB} MB per upload and has no file storage set up for bigger files, and this file is ${megabytes(file.byteLength)} MB. Split it into smaller files and import each under its own name.`, exitCodes.error);
         }
         throw error;
     }
 }
+const TABLES_PATH = "/api/v1/tables";
+function tablePath(name) {
+    return `${TABLES_PATH}/${encodeURIComponent(name)}`;
+}
+/** Refuses an agent table name the server would refuse, before anything is sent. */
+function agentTableName(name) {
+    if (!AGENT_TABLE_NAME_PATTERN.test(name)) {
+        throw new CliError(`"${excerpt(name)}" can't be a table name. Use 1 to 48 lowercase letters, digits and underscores.`, exitCodes.usage);
+    }
+    return name;
+}
+function tableRow(t) {
+    return {
+        table: t.table,
+        rows: t.rows,
+        size: `${megabytes(t.bytes)} MB`,
+        columns: t.columns.map((c) => `${c.name} ${c.type}${c.personal ? "*" : ""}`).join(", "),
+        description: excerpt(t.description ?? "", 60),
+    };
+}
+/** A JSON array of row objects, or one object per line for a .ndjson or .jsonl file. */
+async function readRowsFile(path) {
+    await inRunFolder(path);
+    const text = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            throw new CliError(`No file at ${path}.`, exitCodes.usage);
+        throw error;
+    });
+    const lines = [".ndjson", ".jsonl"].includes(extname(path).toLowerCase());
+    try {
+        const rows = lines ? text.split("\n").filter((l) => l.trim() !== "").map((l) => JSON.parse(l)) : JSON.parse(text);
+        if (!Array.isArray(rows))
+            throw new CliError(`${path} must hold a JSON array of row objects, or one object per line in a .ndjson file.`, exitCodes.usage);
+        if (rows.length === 0)
+            throw new CliError(`${path} has no rows.`, exitCodes.usage);
+        return rows;
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError(`${path} is not valid JSON: ${error.message}`, exitCodes.usage);
+    }
+}
+/** Splits rows into batches the server and its host each take in one request. */
+function rowBatches(rows) {
+    const maxBytes = Math.min(AGENT_TABLE_LIMITS.batchBytes, (HOSTED_UPLOAD_MB - 0.5) * 1024 * 1024);
+    const batches = [];
+    let batch = [];
+    let bytes = 2;
+    for (const row of rows) {
+        const size = Buffer.byteLength(JSON.stringify(row)) + 1;
+        if (batch.length > 0 && (batch.length === AGENT_TABLE_LIMITS.batchRows || bytes + size > maxBytes)) {
+            batches.push(batch);
+            batch = [];
+            bytes = 2;
+        }
+        batch.push(row);
+        bytes += size;
+    }
+    batches.push(batch);
+    return batches;
+}
 /** Refuses a name the server would refuse, before anything is sent. */
 function importName(name) {
     if (!IMPORT_NAME_PATTERN.test(name)) {

package/dist/tool-usage.js

@@ -0,0 +1,35 @@
+import { brand } from "./brand.js";
+import { CliError, exitCodes } from "./api.js";
+export const TOOLS_USAGE_USAGE = "tools usage [--month <YYYY-MM>] [--by tool|run]";
+export const dollars = (cents) => `$${(Math.round(cents) / 100).toFixed(2)}`;
+/** The API path for `tools usage`, and which breakdown to print; the server checks the month. */
+export function toolUsageRequest(flags) {
+    const by = flags.by ?? "tool";
+    if (by !== "tool" && by !== "run")
+        throw new CliError(`--by must be tool or run, not ${JSON.stringify(by)}.`, exitCodes.usage);
+    return { path: `/api/v1/tools/usage${flags.month === undefined ? "" : `?month=${encodeURIComponent(flags.month)}`}`, by };
+}
+/** The statement as text: a heading, one table row per tool or per scheduled run, then the totals and source pulls. */
+export function toolUsageReport(usage, by) {
+    const { totals } = usage;
+    const estimated = totals.estimatedCents > 0 ? ` (${dollars(totals.estimatedCents)} of it estimated)` : "";
+    const footer = [
+        `Total: ${dollars(totals.cents)} over ${totals.runs} ${totals.runs === 1 ? "run" : "runs"}${estimated}. ${brand.name}'s keys ${dollars(totals.platformCents)}, client's keys ${dollars(totals.workspaceCents)}.`,
+        `Source pulls (ScrapeCreators credits for competitor ads, Reddit and Page lookups, not tool runs): ${dollars(usage.sourcePulls.cents)}.`,
+    ];
+    const title = `Tool spend for ${usage.month} (${usage.timeZone})`;
+    if (by === "run") {
+        const rows = usage.byWorkerRun.map((r) => ({ run: r.workerRunId, worker: r.worker, started: r.startedAt ?? "", runs: r.runs, cost: dollars(r.cents) }));
+        if (usage.adHoc.runs > 0)
+            rows.push({ run: "not a scheduled run", worker: "", started: "", runs: usage.adHoc.runs, cost: dollars(usage.adHoc.cents) });
+        return { title, columns: ["run", "worker", "started", "runs", "cost"], rows, footer };
+    }
+    const rows = usage.byTool.map((t) => ({
+        tool: t.tool,
+        provider: t.provider,
+        runs: t.runs,
+        failed: t.failed,
+        cost: t.estimatedOnly > 0 ? `${dollars(t.cents)} (${t.estimatedOnly} estimated)` : dollars(t.cents),
+    }));
+    return { title, columns: ["tool", "provider", "runs", "failed", "cost"], rows, footer };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.53",
+  "version": "0.3.57",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {