@wrangled/cli 0.3.46 → 0.3.48

package/dist/guide.js

@@ -142,6 +142,10 @@ A webhook address lets a tool such as a form or webinar platform push events int
 5. \`${cli} creatives list\` and \`${cli} creatives show <sku>\` read the ledger. \`${cli} creatives download <sku>\` saves a creative's image or video as \`<sku>.<ext>\` in the current folder; \`--out <path>\` names the file or a folder, and \`--open\` opens it. It also takes an asset path or link, such as a \`meta_ad_creatives\` \`image_path\`. \`--format json\` prints \`{ path, bytes, contentType }\`. Copy has no file; its text is in \`${cli} creatives show\`. For performance, query the \`creatives\` table or the \`creative_performance_daily\` view with \`${cli} warehouse query\`.
 6. \`${cli} media list\` lists every image and video the tools made, newest first, whether or not it became a creative: its media id (\`<run id>:<index>\`), tool, prompt, cost and SKU, if any. Narrow it with \`--sku <sku>\`, \`--run <run-id>\` (one batch), \`--tool kie:nano-banana\`, \`--kind image|video\`, \`--since\` and \`--until\` (a day such as \`2026-10-08\`, which \`--until\` counts through its end in UTC, or an ISO time), and \`--limit <n>\` (default 50, at most 200). When more remain it prints the \`--cursor <media-id>\` that shows the next page. A run's cost is split evenly across its outputs and marked as an estimate when the provider did not report a charge. \`${cli} media get <media-id>\` shows the full input that made one, to reuse a good prompt; \`${cli} media download <media-id>\` saves its file, named by its SKU when it has one (\`${cli} creatives download\` takes a media id too). \`--format json\` prints \`{ media, nextCursor }\`.
 
+### The client's own provider keys
+
+A run bills the shared account unless the client has its own key for that provider. A key whose "Can manage settings" switch an admin turned on (Keys page) saves one: \`${cli} secrets set kie < key.txt\`, or \`--file <path>\`. Never type the key on the command line; it stays in the shell history, so the command refuses it. A key with several fields (genesis, vercel) is a JSON object, such as \`{"token": "...", "teamId": "..."}\`. \`${cli} secrets list\` shows which key each provider's runs use (the client's own, the shared one, or none), its field names, when and by whom it was saved, and when a run last read it, never the key itself. \`${cli} secrets remove kie\` puts runs back on the shared key. Meta's key is its source's, changed by connecting the Meta Ads source. A hand's run key can never save or remove keys.
+
 ## Landing pages
 
 The warehouse's content library keeps each landing page's words in order, read about once a day: one \`landing_page\` item per page in \`content_items\`, its versions in \`content_versions\` (\`fields->'blocks'\` holds the headings, paragraphs, lists, buttons, image descriptions and form field labels), and the list of pages with when each was last read in \`content_pages\`. Pages come from Meta ad links and GA4 landing pages. Add any other page with \`${cli} content add-page <url>\`: it is read at once, and the output shows its key, whether it could be read (\`ok\`, \`not_found\`, \`blocked\` by robots.txt, \`failed\`, \`not_html\`), and its version. A link that redirects, such as a link shortener, is recorded under the page it leads to.
@@ -325,6 +329,9 @@ ${cli} import remove --table <name> --yes   drop the table import_<name> and its
 ${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} 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
 ${cli} creatives list               list creatives (--status, --kind, --limit)
 ${cli} creatives show <sku>         show one creative with its spec and lineage
 ${cli} creatives download <sku | media-id | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video

package/dist/main.js

@@ -7,6 +7,8 @@ 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";
 import { AGENTS_MD_MARKER, metaAdsAgentsMd, PLAYBOOK_CHOICES, playbooks } from "./playbooks.js";
@@ -367,6 +369,57 @@ const commands = {
             console.log(renderTable(["key", "label", "value"], settings.fields.map((f) => ({ key: f.key, label: f.label, value: settings.values[f.key] ?? "" }))));
         },
     },
+    "secrets list": {
+        usage: "secrets list   (which provider keys the client has; never the keys themselves)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: secrets list", exitCodes.usage);
+            const { secrets } = await api(await resolveConnection(options), SECRETS_PATH);
+            if (options.format === "json")
+                return printJson({ secrets });
+            const rows = secrets.map((s) => ({
+                provider: s.provider,
+                "key in use": secretSourceLabel(s),
+                fields: s.fields.join(", "),
+                saved: s.updatedAt ?? "",
+                "saved by": s.updatedBy ?? "",
+                "last used": s.lastUsedAt ?? (s.source === "workspace" && s.changedWith === "secrets" ? "never" : ""),
+            }));
+            console.log(renderTable(["provider", "key in use", "fields", "saved", "saved by", "last used"], rows));
+        },
+    },
+    "secrets set": {
+        usage: SECRETS_SET_USAGE,
+        async run(args, options) {
+            const provider = secretProvider(args);
+            const text = options.file
+                ? await readFile(await inRunFolder(options.file), "utf8")
+                : process.stdin.isTTY
+                    ? await promptHidden(`Paste the ${provider} key: `)
+                    : await readStdin();
+            const connection = await resolveConnection(options);
+            const { secret } = await api(connection, secretPath(provider), secretBody(text), "PUT");
+            if (options.format === "json")
+                return printJson({ secret });
+            console.log(`Saved the client's own ${secret.provider} key. Its ${secret.provider} runs now use it instead of the shared one.`);
+        },
+    },
+    "secrets remove": {
+        usage: "secrets remove <provider>   (runs go back to the shared key)",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: secrets remove <provider>", exitCodes.usage);
+            const result = await api(await resolveConnection(options), secretPath(args[0]), undefined, "DELETE");
+            if (options.format === "json")
+                return printJson(result);
+            const { provider } = result.secret;
+            if (!result.removed)
+                return console.log(`The client had no ${provider} key of its own; nothing changed.`);
+            console.log(result.secret.source === "platform"
+                ? `Removed the client's own ${provider} key. Its runs now use the shared key.`
+                : `Removed the client's own ${provider} key. No shared key is set, so its ${provider} runs fail until a key is saved.`);
+        },
+    },
     "intake list": {
         usage: "intake list",
         async run(args, options) {
@@ -2000,6 +2053,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) {
@@ -2595,7 +2714,7 @@ Options:
   --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
   --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
+  --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
   --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
@@ -2653,6 +2772,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
@@ -2773,6 +2902,16 @@ function parseOptions(argv) {
             confidence: { type: "string" },
             remove: { type: "boolean", default: false },
             "dry-run": { 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 },
         },
     });
@@ -2885,6 +3024,20 @@ function parseOptions(argv) {
             confidence: values.confidence,
             remove: values.remove,
             dryRun: values["dry-run"],
+            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"],
+            },
         },
     };
 }
@@ -2894,6 +3047,21 @@ async function changeCandidate(change, args, options) {
         throw new CliError(`Usage: worker ${change} <skill> --workspace <slug>`, exitCodes.usage);
     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)}`;
+}
+function secretSourceLabel(secret) {
+    if (secret.source === "workspace")
+        return secret.changedWith === "meta_source" ? "the Meta source's" : "the client's own";
+    return secret.source === "platform" ? "the shared key" : "none";
+}
 function findCommand(positionals) {
     const three = positionals.slice(0, 3).join(" ");
     if (Object.hasOwn(commands, three))

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/dist/secrets.js

@@ -0,0 +1,35 @@
+import { CliError, exitCodes } from "./api.js";
+import { brand } from "./brand.js";
+export const SECRETS_SET_USAGE = "secrets set <provider> [--file <path>]   (the key on stdin or in the file; JSON {\"field\": \"...\"} for a key with several fields)";
+/**
+ * The provider `secrets set` names. A second argument is refused without being echoed: it is most likely the key,
+ * which would then sit in the shell's history.
+ */
+export function secretProvider(args) {
+    if (args.length > 1) {
+        throw new CliError(`Never pass the key as an argument: it stays in your shell history. Pipe it on stdin (\`${brand.slug} secrets set <provider> < key.txt\`) or name a file with --file.`, exitCodes.usage);
+    }
+    if (args.length === 0)
+        throw new CliError(`Usage: ${SECRETS_SET_USAGE}`, exitCodes.usage);
+    return args[0];
+}
+/** A JSON object of strings is a multi-field key; anything else is the key itself. Error messages never repeat the text. */
+export function secretBody(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        throw new CliError("No key given. Pipe it on stdin or name a file with --file.", exitCodes.usage);
+    if (!trimmed.startsWith("{"))
+        return { value: trimmed };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        throw new CliError('The key starts with "{" but is not valid JSON. A key with several fields is a JSON object, such as {"token": "...", "teamId": "..."}.', exitCodes.usage);
+    }
+    const fields = parsed;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || Object.values(fields).some((v) => typeof v !== "string")) {
+        throw new CliError('A key with several fields is a JSON object of strings, such as {"token": "...", "teamId": "..."}.', exitCodes.usage);
+    }
+    return { fields: fields };
+}

package/package.json

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