@wrangled/cli 0.3.52 → 0.3.56

package/dist/api.js

@@ -21,13 +21,27 @@ 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. */
+export const GOOGLE_ADS_IDS_MAX = 10;
 /** The days before a sale in which a click or reply helps it, as the app counts them (MESSAGE_CREDIT_DAYS). */
 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/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, conversation), \`--platform\` (meta, ghl, klaviyo, roezan, bayengage, activecampaign, mailchimp, hubspot, kit, instantly, kajabi, omnisend, google_ads, tiktok, microsoft_ads, pinterest, linkedin, 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.
 - \`--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.
@@ -187,6 +219,8 @@ The \`meta_ads\` publisher puts an approved ad on Facebook, always paused, in an
 
 \`${cli} meta ad create --account act_<id> --adset <id> --file ad.png --text "<primary text>" --headline "<headline>" --link <https url>\` does all of that in one step: it saves the files and words as an ad with a new SKU, approves it and publishes it with \`meta_ads\` into the ad set, then prints the SKU, the publication, the Meta ad id and its status. Repeat \`--file\` for more pictures; a big file is uploaded first. \`--cta SHOP_NOW\` sets the button and \`--name\` names the ad (the headline otherwise). The same rules apply and are all checked before anything is saved, so a refusal leaves nothing behind. Your own key sends to Facebook without \`--run\`, but the account and campaign must also be on the workspace's control list; from a hand's run in practice mode it is recorded and nothing is sent. The ad starts paused; \`--status active --reason "<why>"\` switches it on 15 seconds after it is made, as a change in the change log that \`${cli} meta changes undo <change-id>\` reverses, and needs room under the day's limit of on/off changes. Without \`--idempotency-key\` the key comes from the files and the flags, so the same command run twice makes one ad.
 
+Google Ads has the same controls. \`${cli} google-ads ads pause <adgroup-id>~<ad-id> --reason "<why>"\` (ids from \`gads_ads\`) and \`${cli} google-ads adgroup pause|resume <adgroup-id>\` turn ads and ad groups off or on, and \`${cli} google-ads campaign budget <campaign-id> --percent 10 --reason "<why>"\` (or \`--daily 60.50\`, in the account's currency) changes a campaign's daily budget. The account and campaign must be on the workspace's Google Ads control list, which an Admin sets on the Settings page, and the same daily limits, largest budget step, total daily budget limit and approval rule apply; a shared budget is never changed. With approval on (the default), a hand proposes \`gads_budget_change\` and the change goes out once a person approves it. Only your own key writes to Google Ads: no hand does yet. \`${cli} google-ads changes\` lists every change with who asked and why, \`${cli} google-ads changes undo <id>\` puts one back, and \`${cli} google-ads changes reconcile <id>\` settles one whose answer was lost.
+
 \`${cli} meta adset publish --plan '<json>' --idempotency-key <key> --run <run-id>\` makes one new Meta ad set, always paused, for ads to go into. A copy, \`{"kind": "copy", "accountId": "act_<id>", "campaignId": "<id>", "sourceAdsetId": "<id>", "name": "<new name>"}\`, copies a proven ad set without its ads; the source must be on the hand's list of ad sets that may be copied. A new one from settings is \`{"kind": "create", "accountId": ..., "campaignId": ..., "name": ..., "settings": {"optimizationGoal": "...", "billingEvent": "...", "targeting": {...}, "dailyBudget": 5000}}\`, with the budget in the currency's smallest unit (5000 is 50.00 USD) and left out when the campaign holds it. The account and campaign must be on the publish list, the name unused in the campaign, and the day under the limit of new ad sets (3 unless an operator sets another). Ad sets and ads share one account's turn: one unfinished send at a time, and at least 15 seconds apart. ${brand.name} reads the new ad set back and checks it: paused, in the right campaign, with the right name, and for a copy, targeting equal to the source's. Its \`verification.ok\` must be true before you add ads; an ad set that fails the check stays paused and takes none. In practice mode nothing is sent and the ad set is recorded as \`not_sent_practice\`, and ads published into it are practice too. \`${cli} meta adset show <id>\` prints it with its budget. One left \`sending\` or \`unknown\` is never sent again; \`${cli} meta adset reconcile <id>\` looks for it in the campaign by its exact name.
 
 When you send something yourself instead, record it in ${brand.name} before anything is sent, so the record never depends on the platform remembering it:
@@ -340,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
@@ -360,9 +395,12 @@ ${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 remove <provider>    remove it, so runs use the shared key again
@@ -386,6 +424,9 @@ ${cli} meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id
 ${cli} meta adset show <id> | meta adset reconcile <id>   read an ad set publication, or check whether one left sending landed
 ${cli} meta ad create --account act_<id> --adset <id> --file <path> --text "<words>" --headline "<h>" --link <url> [--cta <type>] [--name <n>] [--status paused|active --reason "<why>"] [--run <run-id>]   make a Facebook ad from files in one step
 ${cli} meta adset budget <id> | meta campaign budget <id> (--percent <n> | --daily <n>) --reason "<why>"   change a daily budget within the workspace's limits
+${cli} google-ads ads pause|resume <adgroup-id~ad-id>... | google-ads adgroup pause|resume <adgroup-id>... --reason "<why>"   turn Google ads or ad groups on or off
+${cli} google-ads campaign budget <id> (--percent <n> | --daily <amount>) --reason "<why>"   change a Google Ads daily budget within the workspace's limits
+${cli} google-ads changes [--since <date>] | google-ads changes undo <id> --reason "<why>" | google-ads changes reconcile <id>   the Google Ads change log
 ${cli} content publish-record <sku> --file <publication.json>   record a publish before sending it
 ${cli} content publish-finish <publication-id> --status sending|published|failed|not_sent_practice [--input '<json>']
 ${cli} content track-link <sku> <url> [--channel facebook|email|sms|web] [--campaign <id>]   tag a link with its SKU

package/dist/main.js

@@ -5,12 +5,14 @@ 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, 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 { 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";
@@ -20,8 +22,11 @@ import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
 const DEFAULT_WAIT_SECONDS = 300;
 const META_CHANGE_COLUMNS = ["id", "level", "object", "change", "status", "when", "by", "reason"];
+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 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`,
@@ -273,6 +278,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) {
@@ -539,13 +583,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) {
@@ -563,6 +631,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) {
@@ -775,6 +949,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) {
@@ -1031,8 +1221,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);
@@ -1067,6 +1285,74 @@ const commands = {
             printMetaChangeResult({ changes: [change], unchanged: [] }, options.format);
         },
     },
+    "google-ads ads pause": googleAdsStatusCommand("ads", "pause"),
+    "google-ads ads resume": googleAdsStatusCommand("ads", "resume"),
+    "google-ads adgroup pause": googleAdsStatusCommand("adgroup", "pause"),
+    "google-ads adgroup resume": googleAdsStatusCommand("adgroup", "resume"),
+    "google-ads campaign budget": {
+        usage: 'google-ads campaign budget <campaign-id> (--percent <n> | --daily <amount>) --reason "<why>" [--idempotency-key <key>]   change a Google Ads campaign\'s daily budget on the control list, within the workspace\'s limits',
+        async run(args, options) {
+            const usage = 'Usage: google-ads campaign budget <campaign-id> (--percent <n> | --daily <amount>) --reason "<why>" [--idempotency-key <key>]';
+            if (args.length !== 1 || !options.reason || (options.percent === undefined) === (options.daily === undefined))
+                throw new CliError(usage, exitCodes.usage);
+            let amount;
+            if (options.percent !== undefined) {
+                const n = Number(options.percent);
+                if (options.percent.trim() === "" || !Number.isInteger(n))
+                    throw new CliError("--percent must be a whole number.", exitCodes.usage);
+                amount = { changePercent: n };
+            }
+            else {
+                if (!/^\d+(\.\d{1,6})?$/.test(options.daily.trim()))
+                    throw new CliError("--daily must be an amount such as 60 or 60.50.", exitCodes.usage);
+                amount = { dailyBudget: options.daily.trim() };
+            }
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`budget-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), "/api/v1/google-ads/budgets", {
+                campaignId: args[0],
+                ...amount,
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    },
+    "google-ads changes": {
+        usage: "google-ads changes [--since <YYYY-MM-DD>]   the log of Google ads and ad groups turned on or off and budgets changed, newest first",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: google-ads changes [--since <YYYY-MM-DD>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.since)
+                query.set("since", options.since);
+            const { changes } = await api(await resolveConnection(options), `/api/v1/google-ads/changes${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ changes });
+            console.log(changes.length ? renderTable(GOOGLE_ADS_CHANGE_COLUMNS, changes.map(googleAdsChangeRow)) : "No Google Ads changes yet.");
+        },
+    },
+    "google-ads changes undo": {
+        usage: 'google-ads changes undo <change-id> --reason "<why>" [--idempotency-key <key>]   put the ad, ad group or budget back the way it was',
+        async run(args, options) {
+            if (args.length !== 1 || !options.reason)
+                throw new CliError('Usage: google-ads changes undo <change-id> --reason "<why>" [--idempotency-key <key>]', exitCodes.usage);
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`undo-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), `/api/v1/google-ads/changes/${encodeURIComponent(args[0])}/undo`, {
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    },
+    "google-ads changes reconcile": {
+        usage: "google-ads changes reconcile <change-id>   settle a change Google's answer was lost for, from what Google reads now",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: google-ads changes reconcile <change-id>", exitCodes.usage);
+            const { change } = await api(await resolveConnection(options), `/api/v1/google-ads/changes/${encodeURIComponent(args[0])}/reconcile`, {});
+            printGoogleAdsChangeResult({ changes: [change], unchanged: [] }, options.format);
+        },
+    },
     "content unpublish": {
         usage: "content unpublish <deployment-id> [--force]",
         async run(args, options) {
@@ -2061,12 +2347,16 @@ const commands = {
         },
     },
     "proposals execute": {
-        usage: "proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta (live mode only), within the control list",
+        usage: "proposals execute <proposal-id>   apply an approved pause or budget proposal to Meta or Google Ads (live mode only), within the control list",
         async run(args, options) {
             if (args.length !== 1)
                 throw new CliError("Usage: proposals execute <proposal-id>", exitCodes.usage);
             const result = await api(await resolveConnection(options), `/api/v1/proposals/${encodeURIComponent(args[0])}/execute`, {});
-            printMetaChangeResult(result, options.format);
+            const google = result.changes.some((c) => "customerId" in c) || result.unchanged.some((u) => "amountMicros" in u);
+            if (google)
+                printGoogleAdsChangeResult(result, options.format);
+            else
+                printMetaChangeResult(result, options.format);
         },
     },
     "skill publish": {
@@ -2585,6 +2875,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}.`);
@@ -2864,7 +3166,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
@@ -2875,11 +3180,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
@@ -2888,9 +3206,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
@@ -2898,9 +3221,11 @@ 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 and meta ad create --status active record in the change log
-  --percent <n>         with meta adset|campaign budget, the whole-number percent change from Meta's 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)
+  --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
+                        google-ads campaign budget, in the currency itself (60.50 is 60.50 USD)
   --account <act_id>    meta ad create: the ad account
   --adset <id>          meta ad create: the ad set the new ad goes into
   --text <text | @file> meta ad create: the ad's primary text
@@ -2911,7 +3236,7 @@ Options:
   --tool <tool>         with media list, only this tool's outputs, such as kie:nano-banana
   --kind image|video    with media list, only images or only videos
   --since, --until <YYYY-MM-DD | ISO time>   with media list, made at or after --since and before --until (a day: through
-                        its end, in UTC); with meta changes, only changes from --since on
+                        its end, in UTC); with meta changes or google-ads changes, only changes from --since on
   --cursor <media-id>   with media list, the next page: the id it printed after "More"
   --platform, --external-id   where content status launched says it was published, and that platform's id for it
   --object-type <type>  what that platform's sync calls it (campaign_message or flow_message on klaviyo); needed where
@@ -2934,6 +3259,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)
@@ -2944,9 +3270,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;
@@ -2998,6 +3324,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" },
@@ -3015,6 +3343,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" },
@@ -3024,6 +3356,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" },
@@ -3032,6 +3366,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" },
@@ -3041,6 +3377,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" },
@@ -3083,6 +3421,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" },
@@ -3130,6 +3469,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,
@@ -3148,6 +3489,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,
@@ -3157,6 +3502,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,
@@ -3165,6 +3512,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,
@@ -3174,6 +3523,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,
@@ -3216,6 +3567,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,
@@ -3587,7 +3939,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");
@@ -3741,18 +4092,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})`);
@@ -3771,6 +4169,53 @@ function printMetaChangeResult(result, format) {
         console.log(`Meta's answer for change ${c.id} was lost. Run \`${brand.slug} meta changes reconcile ${c.id}\` in a minute to settle it.`);
     }
 }
+function googleAdsStatusCommand(noun, verb) {
+    const usage = `google-ads ${noun} ${verb} <${noun === "ads" ? "adgroup-id~ad-id" : "adgroup-id"}>... --reason "<why>" [--idempotency-key <key>]`;
+    return {
+        usage: `${usage}   ${verb === "pause" ? "turn off" : "turn on"} up to ${GOOGLE_ADS_IDS_MAX} Google ${noun === "ads" ? "ads" : "ad groups"} on the control list`,
+        async run(args, options) {
+            if (args.length === 0 || args.length > GOOGLE_ADS_IDS_MAX || !options.reason)
+                throw new CliError(`Usage: ${usage}`, exitCodes.usage);
+            const idempotencyKey = options.idempotencyKey ?? announceKey(`${verb}-${randomUUID()}`);
+            const result = await api(await resolveConnection(options), "/api/v1/google-ads/changes", {
+                level: noun === "ads" ? "ad" : "ad_group",
+                ids: args,
+                status: verb === "pause" ? "paused" : "enabled",
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printGoogleAdsChangeResult(result, options.format);
+        },
+    };
+}
+/** Micros as the account's currency amount, e.g. 60500000 is 60.50. */
+const fromMicros = (micros) => (Number(micros) / 1_000_000).toFixed(2);
+function googleAdsChangeRow(c) {
+    return {
+        id: c.id,
+        account: c.customerId,
+        level: c.level,
+        object: c.objectId,
+        change: c.kind === "budget" ? `daily budget ${fromMicros(c.before.amountMicros)} -> ${fromMicros(c.after.amountMicros)}` : `${c.before.status} -> ${c.after.status}`,
+        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),
+    };
+}
+function printGoogleAdsChangeResult(result, format) {
+    if (format === "json")
+        return printJson(result);
+    if (result.changes.length > 0)
+        console.log(renderTable(GOOGLE_ADS_CHANGE_COLUMNS, result.changes.map(googleAdsChangeRow)));
+    for (const u of result.unchanged) {
+        const what = { ad: "Ad", ad_group: "Ad group", campaign: "Campaign" }[u.level];
+        console.log("status" in u ? `${what} ${u.objectId} was already ${u.status}; nothing was sent.` : `${what} ${u.objectId}'s daily budget is already ${fromMicros(u.amountMicros)}; nothing was sent.`);
+    }
+    for (const c of result.changes.filter((c) => c.status === "sending")) {
+        console.log(`Google's answer for change ${c.id} was lost. Run \`${brand.slug} google-ads changes reconcile ${c.id}\` in a minute to settle it.`);
+    }
+}
 function printAdSetPublication(publication, format) {
     if (format === "json")
         return printJson({ adsetPublication: publication });
@@ -3849,8 +4294,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.
@@ -3867,13 +4313,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.52",
+  "version": "0.3.56",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {