@wrangled/cli 0.3.47 → 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

@@ -7,6 +7,7 @@ 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 { brand, envPrefix } from "./brand.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 { guide, skill } from "./guide.js";
 import { PULL_STATE_FILE, pullContent } from "./pull.js";
@@ -1805,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) {
@@ -2052,6 +2130,72 @@ const commands = {
             console.log(`Stopped trying ${dropped.skill} version ${dropped.version} on ${dropped.workspace}. Runs stay on version ${dropped.versionInUse}.`);
         },
     },
+    "schedules list": {
+        usage: "schedules list   (the client's scheduled hands, and who set each one up)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: schedules list", exitCodes.usage);
+            const { schedules } = await api(await resolveConnection(options), SCHEDULES_PATH);
+            if (options.format === "json")
+                return printJson({ schedules });
+            if (schedules.length === 0)
+                return console.log("No scheduled hands yet.");
+            const rows = schedules.map((w) => ({
+                id: w.id,
+                skill: w.skill,
+                schedule: `${w.schedule} ${w.timeZone}`,
+                runner: w.runner,
+                enabled: w.enabled ? "yes" : "no",
+                "next run": w.nextRunAt,
+                "set up by": w.createdBy ?? "operator",
+            }));
+            console.log(renderTable(["id", "skill", "schedule", "runner", "enabled", "next run", "set up by"], rows));
+        },
+    },
+    "schedules create": {
+        usage: `${SCHEDULES_CREATE_USAGE}   (a key that can manage settings)`,
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError(`Usage: ${SCHEDULES_CREATE_USAGE}`, exitCodes.usage);
+            const file = options.schedule.promptFile;
+            const body = scheduleCreateBody(options.schedule, file === undefined ? null : await readFile(await inRunFolder(file), "utf8"));
+            const { schedule, created } = await api(await resolveConnection(options), SCHEDULES_PATH, body);
+            if (options.format === "json")
+                return printJson({ schedule, created });
+            console.log(`${created ? "Set up" : "Changed"} the scheduled hand ${schedule.skill} (${schedule.id}): ${schedule.schedule} ${schedule.timeZone}, next run ${schedule.nextRunAt}.`);
+        },
+    },
+    ...Object.fromEntries([
+        ["pause", false, "Paused", "It does not run on its schedule until resumed."],
+        ["resume", true, "Resumed", "Its next run is"],
+    ].map(([verb, enabled, done, then]) => [
+        `schedules ${verb}`,
+        {
+            usage: `schedules ${verb} <id | skill | name>   (a key that can manage settings)`,
+            async run(args, options) {
+                if (args.length !== 1)
+                    throw new CliError(`Usage: schedules ${verb} <id | skill | name>`, exitCodes.usage);
+                const connection = await resolveConnection(options);
+                const id = await scheduleId(connection, args[0]);
+                const { schedule } = await api(connection, schedulePath(id), { enabled }, "PATCH");
+                if (options.format === "json")
+                    return printJson({ schedule });
+                console.log(`${done} ${schedule.skill}. ${enabled ? `${then} ${schedule.nextRunAt}.` : then}`);
+            },
+        },
+    ])),
+    "schedules delete": {
+        usage: "schedules delete <id | skill | name>   (a key that can manage settings; its past runs are kept)",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: schedules delete <id | skill | name>", exitCodes.usage);
+            const connection = await resolveConnection(options);
+            const result = await api(connection, schedulePath(await scheduleId(connection, args[0])), undefined, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Deleted the scheduled hand ${result.deleted.skill}. It no longer runs; its past runs are kept.`);
+        },
+    },
     "runner once": {
         usage: `runner once [--run <id>] [--max-seconds <n>]   (takes the runner token in ${RUNNER_TOKEN_ENV})`,
         async run(args, options) {
@@ -2559,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}.`);
@@ -2705,6 +2869,16 @@ Options:
   --kind email|text|page   with content tags and content autotag, only that kind (content autotag takes a comma list)
   --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
   --workspace <slug>    for worker promote and worker drop: the workspace whose hand they change
+  --skill <name>[@<n>]  schedules create: the library skill the hand runs (its latest version unless @n)
+  --name <name> --prompt-file <path>   schedules create: save the file (at most 64 KB) as this client's own skill
+                        sched-<client code>-<name> and run that instead; changed text adds a new version
+  --cron "<5 fields>"   schedules create: when it runs, like "0 9 * * 1" for Mondays at 9:00
+  --time-zone <zone>    schedules create: the time zone --cron is read in (default: the client's reporting time zone)
+  --runner mac_mini|trigger   schedules create: where it runs (trigger, the cloud, is refused until it is live)
+  --harness claude|codex, --model <id>, --prompt <text>, --deadline-minutes <1-60>   schedules create: the agent, model,
+                        run prompt and time limit of each run
+  --ai-cap-cents, --tool-cap-cents <n>   schedules create: what one run may spend on AI and on images and video, at most
+                        1000 and 2000 cents
   -h, --help            show this help
 
 skill publish, skill list and skill install <name> use the skill library, which takes the operator token in
@@ -2825,6 +2999,17 @@ 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" },
+            runner: { type: "string" },
+            model: { type: "string" },
+            prompt: { type: "string" },
+            "prompt-file": { type: "string" },
+            "deadline-minutes": { type: "string" },
+            "ai-cap-cents": { type: "string" },
+            "tool-cap-cents": { type: "string" },
             help: { type: "boolean", short: "h", default: false },
         },
     });
@@ -2937,6 +3122,21 @@ function parseOptions(argv) {
             confidence: values.confidence,
             remove: values.remove,
             dryRun: values["dry-run"],
+            data: values.data,
+            schedule: {
+                skill: values.skill,
+                name: values.name,
+                promptFile: values["prompt-file"],
+                cron: values.cron,
+                timeZone: values["time-zone"],
+                runner: values.runner,
+                harness: values.harness,
+                model: values.model,
+                prompt: values.prompt,
+                deadlineMinutes: values["deadline-minutes"],
+                aiCapCents: values["ai-cap-cents"],
+                toolCapCents: values["tool-cap-cents"],
+            },
         },
     };
 }
@@ -2947,6 +3147,12 @@ async function changeCandidate(change, args, options) {
     return api(await operatorConnection(options), `/api/operator/workers/${change}`, { workspace: options.workspace, skill: args[0] });
 }
 const SECRETS_PATH = "/api/v1/secrets";
+const SCHEDULES_PATH = "/api/v1/schedules";
+const schedulePath = (id) => `${SCHEDULES_PATH}/${encodeURIComponent(id)}`;
+async function scheduleId(connection, ref) {
+    const { schedules } = await api(connection, SCHEDULES_PATH);
+    return scheduleIdFor(schedules, ref);
+}
 function secretPath(provider) {
     return `${SECRETS_PATH}/${encodeURIComponent(provider)}`;
 }

package/dist/schedules.js

@@ -0,0 +1,55 @@
+import { CliError, exitCodes } from "./api.js";
+export const SCHEDULES_CREATE_USAGE = 'schedules create (--skill <name>[@<version>] | --name <name> --prompt-file <path>) --cron "<5 fields>" [--time-zone <zone>] ' +
+    "[--runner mac_mini|trigger] [--harness claude|codex] [--model <id>] [--prompt <text>] [--deadline-minutes <n>] [--ai-cap-cents <n>] [--tool-cap-cents <n>]";
+const usage = (problem) => new CliError(`${problem}\nUsage: ${SCHEDULES_CREATE_USAGE}`, exitCodes.usage);
+function whole(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw usage(`--${flag} must be a whole number; got '${raw}'.`);
+    return Number(raw);
+}
+/**
+ * What POST /api/v1/schedules takes for these flags. `promptFileText` is the text of --prompt-file, read by the caller.
+ * The server checks the values themselves; this only checks the flags fit together.
+ */
+export function scheduleCreateBody(flags, promptFileText) {
+    const fromFile = flags.name !== undefined || flags.promptFile !== undefined;
+    if ((flags.skill === undefined) === !fromFile)
+        throw usage("Give --skill, or --name with --prompt-file: one of the two.");
+    if (fromFile && (flags.name === undefined || flags.promptFile === undefined))
+        throw usage("--name and --prompt-file go together.");
+    if (flags.cron === undefined)
+        throw usage("--cron is required.");
+    const body = {
+        skill: flags.skill,
+        name: flags.name,
+        promptFile: fromFile ? (promptFileText ?? "") : undefined,
+        schedule: flags.cron,
+        timeZone: flags.timeZone,
+        runner: flags.runner,
+        harness: flags.harness,
+        model: flags.model,
+        prompt: flags.prompt,
+        deadlineMinutes: whole("deadline-minutes", flags.deadlineMinutes),
+        aiCapCents: whole("ai-cap-cents", flags.aiCapCents),
+        toolCapCents: whole("tool-cap-cents", flags.toolCapCents),
+    };
+    return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined));
+}
+/**
+ * The id of the hand `ref` names: its id, its skill, or for a hand made from a prompt file (skill
+ * `sched-<workspace code>-<name>`), the name it was given, when exactly one hand has it.
+ */
+export function scheduleIdFor(schedules, ref) {
+    const exact = schedules.find((s) => s.id === ref.toLowerCase()) ?? schedules.find((s) => s.skill === ref);
+    if (exact)
+        return exact.id;
+    const named = schedules.filter((s) => /^sched-[a-z0-9]+-/.test(s.skill) && s.skill.replace(/^sched-[a-z0-9]+-/, "") === ref);
+    if (named.length === 1)
+        return named[0].id;
+    if (named.length > 1) {
+        throw new CliError(`More than one scheduled hand is named ${JSON.stringify(ref)} (${named.map((s) => s.skill).join(", ")}); give its id or full skill name.`, exitCodes.usage);
+    }
+    throw new CliError(`schedule_not_found: no scheduled hand with id, skill or name ${JSON.stringify(ref)} in this workspace`, exitCodes.error);
+}

package/package.json

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