@wrangled/cli 0.3.48 → 0.3.49

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

@@ -1806,6 +1806,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 +2703,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}.`);
@@ -2902,6 +2999,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" },
@@ -3024,6 +3122,7 @@ function parseOptions(argv) {
             confidence: values.confidence,
             remove: values.remove,
             dryRun: values["dry-run"],
+            data: values.data,
             schedule: {
                 skill: values.skill,
                 name: values.name,

package/package.json

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