@wrangled/cli 0.3.48 → 0.3.50

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" };
+/** The most ads or ad sets one meta ads|adset pause|resume sends; the server refuses more. */
+export const META_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. */

package/dist/guide.js

@@ -17,6 +17,24 @@ export const funnelTestExample = {
     split_method: "adzara_ads",
     evidence: [{ kind: "customer_words", ref: "sales call 2026-09-30", note: "I didn't know what the webinar was about." }],
 };
+/** The dashboard the guide shows; the app's parser must accept it (src/lib/cli-consistency.test.ts). */
+export const dashboardExample = {
+    title: "Daily ads and leads",
+    dateRange: { default: "30d", picker: true },
+    panels: [
+        {
+            id: "spend",
+            title: "Ad spend by day",
+            sql: "SELECT date, sum(spend) AS spend FROM daily_funnel WHERE date BETWEEN {{from}} AND {{to}} GROUP BY date ORDER BY date",
+            chart: "line",
+            x: "date",
+            y: ["spend"],
+            format: { spend: "money" },
+            width: 2,
+        },
+        { id: "leads", title: "Leads", sql: "SELECT sum(leads) AS leads FROM daily_funnel WHERE date BETWEEN {{from}} AND {{to}}", chart: "number", y: ["leads"], format: { leads: "count" } },
+    ],
+};
 export const guide = `# ${brand.name} CLI
 
 \`${cli}\` gives read-only SQL access to one client's marketing data warehouse (ad spend, orders, and other synced sources), runs paid generation and research tools for that client, and keeps the creative ledger. Each API key belongs to exactly one workspace, and every command works only in that workspace.
@@ -266,6 +284,20 @@ Each section's \`audience\` is \`staff\`, \`client\` or \`both\`; a person on st
 
 The story hand writes it each week. Its playbook installs with \`${cli} skill install story\` as the \`${STORY_SKILL_NAME}\` skill and prints with \`${cli} docs story\`.
 
+## Team dashboards
+
+A team dashboard is a page of charts the team opens for one client, such as daily ad spend, leads and cost per lead with a date picker. You write it as a short spec; ${brand.name} saves it and reads every number live each time someone opens it, so nothing is copied out. \`${cli} dashboards create --file spec.json\` publishes one (or pipe the spec on stdin):
+
+\`\`\`json
+${JSON.stringify(dashboardExample)}
+\`\`\`
+
+Each panel is one SQL query and how to draw it: \`chart\` is \`line\`, \`bar\`, \`area\`, \`table\` or \`number\`. A line, bar or area panel names its \`x\` column and its \`y\` columns; a number panel one \`y\` column. \`format\` marks columns as \`money\`, \`count\` or \`percent\`, and \`width\` 2 takes the full row. \`dateRange.default\` is \`7d\`, \`30d\`, \`90d\`, \`this-month\` or \`last-month\`, and \`picker\` shows a date picker. Write \`{{from}}\` and \`{{to}}\` where the page's first and last day go; the server binds them as dates in the client's reporting time zone, and refuses any other \`{{...}}\`. A dashboard has at most 20 panels and 20 KB of SQL in each.
+
+Before saving, the server runs every panel once over the default range as this workspace's reader. A panel that fails, or lacks a column it names, refuses the whole spec with the panel's id and, when it knows one, a hint at the right name. The answer has \`url\`, the link that opens the dashboard for this client: give it to the person who asked.
+
+\`${cli} dashboards update <slug> --file spec.json\` publishes the next version of the whole spec, \`${cli} dashboards rollback <slug> --version <n>\` publishes an earlier version's spec again as the next version, and \`${cli} dashboards archive <slug>\` takes one down. \`${cli} dashboards list\` lists them, and \`${cli} dashboards show <slug> --data\` prints the spec, every version, and each panel's rows now (\`--from\` and \`--to\` pick the days), so you can check the numbers.
+
 ## The Facebook ads agent
 
 The daily Facebook ads agent follows its own playbook: install it with \`${cli} skill install meta-ads\` (or \`--codex\` for an AGENTS.md in the current directory) and read it with \`${cli} docs meta-ads\`. It works in runs (\`${cli} agent start\`, \`${cli} agent finish\`), reads and suggests settled facts (\`${cli} facts\`), keeps a brand profile (\`${cli} brand\`), and makes proposals (\`${cli} proposals\`) that a person approves in the web app. Nothing it does is sent to Meta.
@@ -383,6 +415,8 @@ ${cli} voice lists                  where that voice comes from: the competitors
 ${cli} voice suggest competitor|subreddit|search_phrase "<value>" [--note <why>]   suggest a competitor, subreddit or Reddit search phrase for a person to approve
 ${cli} story [--json] | story list | story show <version>   the weekly story, its versions, and the rows behind each sentence
 ${cli} story submit --file <story.json>   save the next version of the weekly story
+${cli} dashboards list | dashboards show <slug> [--data] [--from <date>] [--to <date>]   the team dashboards, one's panels and versions, and its numbers now
+${cli} dashboards create --file <spec.json> | dashboards update <slug> --file <spec.json> | dashboards rollback <slug> --version <n> | dashboards archive <slug>
 ${cli} worker list | worker runs <hand-id | skill> [--limit <n>] | worker run-now <hand-id | skill>   this workspace's scheduled hands, their runs and costs, and Run now
 ${cli} skill install [${PLAYBOOK_CHOICES}] [--project] [--codex]   install a Claude Code skill (or the playbook for Codex)
 ${cli} docs [${PLAYBOOK_CHOICES}]   print this guide, or a hand's playbook

package/dist/main.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 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, 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, IMPORT_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { scheduleCreateBody, scheduleIdFor, SCHEDULES_CREATE_USAGE } from "./schedules.js";
@@ -17,6 +18,7 @@ import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } fr
 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 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 commands = {
@@ -997,6 +999,46 @@ const commands = {
             printAdSetPublication(adsetPublication, options.format);
         },
     },
+    "meta ads pause": metaStatusCommand("ads", "pause"),
+    "meta ads resume": metaStatusCommand("ads", "resume"),
+    "meta adset pause": metaStatusCommand("adset", "pause"),
+    "meta adset resume": metaStatusCommand("adset", "resume"),
+    "meta changes": {
+        usage: "meta changes [--since <YYYY-MM-DD>]   the log of Meta ads and ad sets turned on or off, newest first",
+        async run(args, options) {
+            if (args.length !== 0)
+                throw new CliError("Usage: meta 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/meta/changes${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ changes });
+            console.log(changes.length ? renderTable(META_CHANGE_COLUMNS, changes.map(metaChangeRow)) : "No Meta changes yet.");
+        },
+    },
+    "meta changes undo": {
+        usage: 'meta changes undo <change-id> --reason "<why>" [--idempotency-key <key>]   put the ad or ad set back the way it was',
+        async run(args, options) {
+            if (args.length !== 1 || !options.reason)
+                throw new CliError('Usage: meta 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/meta/changes/${encodeURIComponent(args[0])}/undo`, {
+                reason: options.reason,
+                idempotencyKey,
+            });
+            printMetaStatusResult(result, options.format);
+        },
+    },
+    "meta changes reconcile": {
+        usage: "meta changes reconcile <change-id>   settle a change Meta's answer was lost for, from what Meta reads now",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: meta changes reconcile <change-id>", exitCodes.usage);
+            const { change } = await api(await resolveConnection(options), `/api/v1/meta/changes/${encodeURIComponent(args[0])}/reconcile`, {});
+            printMetaStatusResult({ changes: [change], unchanged: [] }, options.format);
+        },
+    },
     "content unpublish": {
         usage: "content unpublish <deployment-id> [--force]",
         async run(args, options) {
@@ -1806,6 +1848,83 @@ const commands = {
             printStory(story);
         },
     },
+    "dashboards list": {
+        usage: "dashboards list   the team dashboards, the most recently changed first, with the link that opens each",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: dashboards list", exitCodes.usage);
+            const { dashboards } = await api(await resolveConnection(options), DASHBOARDS_PATH);
+            if (options.format === "json")
+                return printJson({ dashboards });
+            if (dashboards.length === 0)
+                return console.log("No dashboards yet.");
+            console.log(renderTable(["slug", "title", "version", "updated", "url"], dashboards.map((d) => ({ ...d, updated: d.updatedAt }))));
+        },
+    },
+    "dashboards show": {
+        usage: "dashboards show <slug> [--data] [--from <date>] [--to <date>]   one dashboard's panels and versions; --data reads every panel's rows now",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: dashboards show <slug> [--data] [--from <date>] [--to <date>]", exitCodes.usage);
+            if (!options.data && (options.from !== undefined || options.to !== undefined))
+                throw new CliError("--from and --to go with --data.", exitCodes.usage);
+            const connection = await resolveConnection(options);
+            const { dashboard } = await api(connection, dashboardPath(args[0]));
+            let data;
+            if (options.data) {
+                const range = new URLSearchParams(Object.entries({ from: options.from, to: options.to }).filter((e) => e[1] !== undefined));
+                data = JSON.parse(await apiText(connection, `${dashboardPath(args[0])}/data${range.size > 0 ? `?${range}` : ""}`), keepRawNumbers);
+            }
+            if (options.format === "json")
+                return printJson(data ? { dashboard, data } : { dashboard });
+            printDashboard(dashboard, data);
+        },
+    },
+    "dashboards create": {
+        usage: "dashboards create --file <spec.json> | < spec.json   publish a new dashboard once every panel runs",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: dashboards create --file <spec.json> | < spec.json", exitCodes.usage);
+            const { dashboard } = await api(await resolveConnection(options), DASHBOARDS_PATH, await readToolInput(options));
+            if (options.format === "json")
+                return printJson({ dashboard });
+            console.log(`Published dashboard ${dashboard.slug}, version ${dashboard.version}.\n${dashboard.url}`);
+        },
+    },
+    "dashboards update": {
+        usage: "dashboards update <slug> --file <spec.json> | < spec.json   publish the dashboard's next version once every panel runs",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: dashboards update <slug> --file <spec.json> | < spec.json", exitCodes.usage);
+            const { dashboard } = await api(await resolveConnection(options), dashboardPath(args[0]), await readToolInput(options), "PUT");
+            if (options.format === "json")
+                return printJson({ dashboard });
+            console.log(`Published dashboard ${dashboard.slug}, version ${dashboard.version}.\n${dashboard.url}`);
+        },
+    },
+    "dashboards rollback": {
+        usage: "dashboards rollback <slug> --version <n>   publish an earlier version's spec again, as the next version",
+        async run(args, options) {
+            if (args.length !== 1 || options.version === undefined)
+                throw new CliError("Usage: dashboards rollback <slug> --version <n>", exitCodes.usage);
+            const version = wholeNumber(options.version, "--version");
+            const { dashboard } = await api(await resolveConnection(options), `${dashboardPath(args[0])}/rollback`, { version });
+            if (options.format === "json")
+                return printJson({ dashboard });
+            console.log(`Published version ${version}'s spec as dashboard ${dashboard.slug}, version ${dashboard.version}.\n${dashboard.url}`);
+        },
+    },
+    "dashboards archive": {
+        usage: "dashboards archive <slug>   take a dashboard down; its versions are kept, and publishing at its slug brings it back",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: dashboards archive <slug>", exitCodes.usage);
+            const { archived } = await api(await resolveConnection(options), dashboardPath(args[0]), undefined, "DELETE");
+            if (options.format === "json")
+                return printJson({ archived });
+            console.log(`Archived dashboard ${archived.slug}.`);
+        },
+    },
     "story submit": {
         usage: "story submit --file <story.json> | < story.json   save the next version; the server runs each query and keeps its rows",
         async run(args, options) {
@@ -2626,6 +2745,26 @@ function nameKeyLines(value) {
     return ["", "Name patterns:", ...(patterns.length > 0 ? patterns : ["- none yet"]), "", "Open questions:", ...(questions.length > 0 ? questions : ["- none"])];
 }
 const STORIES_PATH = "/api/v1/stories";
+const DASHBOARDS_PATH = "/api/v1/dashboards";
+const dashboardPath = (slug) => `${DASHBOARDS_PATH}/${encodeURIComponent(slug)}`;
+function printDashboard(dashboard, data) {
+    console.log(`${dashboard.title}: version ${dashboard.version}, updated ${dashboard.updatedAt}.\n${dashboard.url}`);
+    const range = dashboard.spec.dateRange;
+    if (range)
+        console.log(`Default range ${range.default}${range.picker ? ", with a date picker" : ""}.`);
+    console.log(`\n${renderTable(["panel", "title", "chart", "x", "y"], dashboard.spec.panels.map((p) => ({ panel: p.id, title: p.title, chart: p.chart, x: p.x, y: p.y?.join(", ") })))}`);
+    console.log(`\nVersions:\n${renderTable(["version", "by", "at"], dashboard.versions.map((v) => ({ version: v.version, by: v.createdBy, at: v.createdAt })))}`);
+    if (!data)
+        return;
+    console.log(`\nNumbers from ${data.range.from} to ${data.range.to}:`);
+    for (const panel of data.panels) {
+        console.log(`\n${panel.id}`);
+        if ("error" in panel)
+            console.log(`failed: ${panel.error.message}${panel.error.hint ? `\nHint: ${panel.error.hint}` : ""}`);
+        else
+            console.log(`${renderTable(panel.columns.map((c) => c.name), panel.rows)}${panel.truncated ? `\n(cut off at the ${panel.truncated.replace("_", " ")})` : ""}`);
+    }
+}
 function printStory(story) {
     const corrects = story.previousId ? `, correcting ${story.previousId}` : "";
     console.log(`Story version ${story.version}, up to ${story.periodEnd}, saved ${story.createdAt} by ${story.author}${corrects}.`);
@@ -2720,13 +2859,14 @@ Options:
   --source <text>       where the content content capture saves came from, in words
   --url <url>           the address of the content content capture saves
   --tool-run <id>       a succeeded tool run content create and edit link; repeat for several
-  --run <id>            the agent run making the content (content), the tool run to record (creatives create), or the tool
-                        run whose outputs media list shows
+  --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 and meta changes undo record in the change log
   --sku <sku>           with media list, only the output that became this creative
   --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)
+                        its end, in UTC); with meta 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
@@ -2819,6 +2959,7 @@ function parseOptions(argv) {
             ad: { type: "string" },
             limit: { type: "string" },
             run: { type: "string" },
+            reason: { type: "string" },
             lineage: { type: "string" },
             tags: { type: "string" },
             sources: { type: "string" },
@@ -2902,6 +3043,7 @@ function parseOptions(argv) {
             confidence: { type: "string" },
             remove: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
+            data: { type: "boolean", default: false },
             skill: { type: "string" },
             cron: { type: "string" },
             "time-zone": { type: "string" },
@@ -2943,6 +3085,7 @@ function parseOptions(argv) {
             ad: values.ad,
             limit: values.limit,
             run: values.run,
+            reason: values.reason,
             lineage: values.lineage,
             tags: values.tags,
             sources: values.sources,
@@ -3024,6 +3167,7 @@ function parseOptions(argv) {
             confidence: values.confidence,
             remove: values.remove,
             dryRun: values["dry-run"],
+            data: values.data,
             schedule: {
                 skill: values.skill,
                 name: values.name,
@@ -3482,6 +3626,54 @@ function printPublication(publication, format) {
         finished: publication.finishedAt,
     });
 }
+function metaStatusCommand(noun, verb) {
+    const usage = `meta ${noun} ${verb} <${noun === "ads" ? "ad" : "adset"}-id>... --reason "<why>" [--run <run-id>] [--idempotency-key <key>]`;
+    return {
+        usage: `${usage}   ${verb === "pause" ? "turn off" : "turn on"} up to ${META_IDS_MAX} ${noun === "ads" ? "ads" : "ad sets"} on the control list`,
+        async run(args, options) {
+            if (args.length === 0 || args.length > META_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/meta/changes", {
+                level: noun === "ads" ? "ad" : "adset",
+                ids: args,
+                status: verb === "pause" ? "paused" : "active",
+                reason: options.reason,
+                idempotencyKey,
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printMetaStatusResult(result, options.format);
+        },
+    };
+}
+function metaChangeRow(c) {
+    return {
+        id: c.id,
+        level: c.level,
+        object: c.objectId,
+        change: `${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),
+    };
+}
+/** 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})`);
+    return key;
+}
+function printMetaStatusResult(result, format) {
+    if (format === "json")
+        return printJson(result);
+    if (result.changes.length > 0)
+        console.log(renderTable(META_CHANGE_COLUMNS, result.changes.map(metaChangeRow)));
+    for (const u of result.unchanged)
+        console.log(`${u.level === "ad" ? "Ad" : "Ad set"} ${u.objectId} was already ${u.status}; nothing was sent.`);
+    for (const c of result.changes.filter((c) => c.status === "sending")) {
+        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 printAdSetPublication(publication, format) {
     if (format === "json")
         return printJson({ adsetPublication: publication });

package/package.json

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