@wrangled/cli 0.3.45 → 0.3.47

package/dist/guide.js

@@ -140,6 +140,11 @@ A webhook address lets a tool such as a form or webinar platform push events int
 3. A run that is still going prints its id. Check it with \`${cli} tools get <run-id>\`. Image results list an \`asset\` link. Save the file with \`${cli} creatives download <asset-link>\`, or fetch the link with your API key as a bearer token; it redirects to a copy that works for 10 minutes.
 4. Record a succeeded run in the ledger with its lineage: \`${cli} creatives create --run <run-id> --lineage '{"persona": "...", "painPoint": "...", "desiredOutcome": "...", "angle": "...", "sourceAd": {"metaAdId": "..."}}'\`. Each output gets a SKU such as \`DLC-000123\`. The SKU goes in the Meta ad name. Lineage is free-text notes; give the ad's marketing tags with \`--tags '<json>'\` or \`--tags @tags.json\`, the same fields as ad tags (see Ad tags), such as \`{"offer_key": "course", "landing_funnel_key": "webinar_to_course", "landing_step_key": "registration_page", "persona": "near_retirement", "angle": "story", "format": "image"}\`. Every output of the run gets them. Values come from \`${cli} grammar\`; persona and concept from this client's lists, and offer, funnel and step from its confirmed map (\`${cli} funnels show\`), where the step must be in that funnel and \`reply\` or \`no_link\` take no step. A value off them is refused with the ones to use. Recording the same run again returns its creatives as they are, tags included; \`${cli} creatives tag <sku> --file tags.json\` is how to change a creative's tags. Your tags read proposed until an Owner or Admin confirms them on the creative's page in Content; after that only a person changes them.
 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
 
@@ -324,11 +329,17 @@ ${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 | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video
+${cli} creatives download <sku | media-id | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video
 ${cli} creatives create --run <run-id> [--lineage '<json>' | @file.json] [--tags '<json>' | @file.json]   record a run's output with a new SKU
 ${cli} creatives tag <sku> --file <tags.json>   replace a creative's marketing tags, proposed until a person confirms them
+${cli} media list                   list every made image and video (--sku, --run, --tool, --kind, --since, --until, --limit, --cursor)
+${cli} media get <media-id>         show the tool, model, full input and cost that made one
+${cli} media download <media-id> [--out <path>] [--open]   save a made image or video
 ${cli} content create --kind <kind> [--body ...] [--file <path>] [--note <why>] [--plan <plan-id>]   save made content with a new SKU
 ${cli} content search [--text <words>] [--mode word|meaning] [--kind <kind>] [--platform <p>] [--origin <o>] [--from <date>] [--to <date>] [--sort <column>] [--order asc|desc] [--limit <n>]   find content with its numbers
 ${cli} content pull <dir> [--kind <kind>] [--platform <p>] [--origin <o>] [--media] [--full]   copy the library to a folder of Markdown files; rerun for changes

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 { 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 +368,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) {
@@ -545,20 +597,11 @@ const commands = {
         },
     },
     "creatives download": {
-        usage: "creatives download <sku | asset-path | asset-link> [--out <path>] [--open]",
+        usage: "creatives download <sku | media-id | asset-path | asset-link> [--out <path>] [--open]",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: creatives download <sku | asset-path | asset-link> [--out <path>] [--open]", exitCodes.usage);
-            const connection = await resolveConnection(options);
-            const target = await downloadTarget(args[0], connection);
-            const { bytes, contentType } = await apiDownload(connection, `${ASSET_ROUTE}${target.assetPath.split("/").map(encodeURIComponent).join("/")}`);
-            const path = await savePath(options.out, extname(target.fileName) ? target.fileName : `${target.fileName}.${extensionFor(contentType)}`);
-            await saveFile(path, bytes);
-            if (options.open)
-                openFile(resolve(path));
-            if (options.format === "json")
-                return printJson({ path: resolve(path), bytes: bytes.byteLength, contentType });
-            console.log(`Saved ${target.label} to ${path} (${fileSize(bytes.byteLength)}).`);
+                throw new CliError("Usage: creatives download <sku | media-id | asset-path | asset-link> [--out <path>] [--open]", exitCodes.usage);
+            await download(args[0], options);
         },
     },
     "creatives create": {
@@ -591,6 +634,48 @@ const commands = {
             console.log(`Tagged ${creative.sku}. The tags read ${creative.tagsStatus} until a person confirms them in the app.`);
         },
     },
+    "media list": {
+        usage: "media list [--sku <sku>] [--run <tool-run-id>] [--tool <tool>] [--kind image|video] [--since <date>] [--until <date>] [--limit <n>] [--cursor <media-id>]",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: media list [--sku <sku>] [--run <tool-run-id>] [--tool <tool>] [--kind image|video] [--since <date>] [--until <date>] [--limit <n>] [--cursor <media-id>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            for (const name of ["sku", "run", "tool", "kind", "since", "until", "limit", "cursor"]) {
+                if (options[name])
+                    query.set(name, options[name]);
+            }
+            const page = await api(await resolveConnection(options), `/api/v1/media${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson(page);
+            if (page.media.length === 0)
+                return console.log("No made images or videos match.");
+            const rows = page.media.map((m) => ({ ...m, prompt: excerpt(m.prompt ?? ""), cost: costLabel(m), sku: m.sku ?? "" }));
+            console.log(renderTable(["id", "tool", "prompt", "cost", "sku", "createdAt", "assetUrl"], rows));
+            if (page.nextCursor)
+                console.log(`\nMore: add --cursor ${page.nextCursor}`);
+        },
+    },
+    "media get": {
+        usage: "media get <media-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: media get <media-id>", exitCodes.usage);
+            const { media } = await api(await resolveConnection(options), mediaPath(args[0]));
+            if (options.format === "json")
+                return printJson({ media });
+            const fields = { ...media, cost: costLabel(media) };
+            const shown = ["id", "tool", "model", "prompt", "input", "cost", "contentType", "sku", "creativeStatus", "assetUrl", "workerRunId", "createdAt"];
+            console.log(renderTable(["field", "value"], shown.filter((f) => fields[f] != null).map((f) => ({ field: f, value: fields[f] }))));
+        },
+    },
+    "media download": {
+        usage: "media download <media-id> [--out <path>] [--open]",
+        async run(args, options) {
+            if (args.length !== 1 || !parseMediaId(args[0]))
+                throw new CliError("Usage: media download <media-id> [--out <path>] [--open]", exitCodes.usage);
+            await download(args[0], options);
+        },
+    },
     "content create": {
         usage: "content create --kind <kind> [--name <name>] [--subject <s>] [--preview <s>] [--headline <s>] [--body <text> | @file] [--html @file] [--fields '<json>' | @file.json] [--file <path> ...] [--tool-run <id> ...] [--run <agent-run-id>] [--note <why>] [--plan <plan-id> [--role <role>]]",
         async run(args, options) {
@@ -2539,11 +2624,11 @@ Options:
                         for warehouse schema, a table to describe in full; repeat for several
   --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 and warehouse query save to; warehouse query
+  --out <path>          the file, or existing folder, creatives download, media download and warehouse query save to; warehouse query
                         writes CSV for a .csv path, otherwise JSON
   --all                 with warehouse query --out, save the whole answer (up to 1,000,000 rows or 50 MiB) instead of
                         the first 1,000 rows or 5 MiB; .ndjson or .jsonl saves one JSON row per line
-  --open                open the file creatives download saved
+  --open                open the file creatives download or media download saved
   --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
@@ -2562,13 +2647,20 @@ 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
   --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), or the tool run to record (creatives create)
+  --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
+  --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)
+  --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
                         the sync matches several kinds, so its next read joins the item
@@ -2600,9 +2692,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, 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
+                        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)
   --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;
@@ -2669,6 +2761,10 @@ function parseOptions(argv) {
             yes: { type: "boolean", default: false },
             from: { type: "string" },
             since: { type: "string" },
+            until: { type: "string" },
+            sku: { type: "string" },
+            tool: { type: "string" },
+            cursor: { type: "string" },
             to: { type: "string" },
             grain: { type: "string" },
             channel: { type: "string" },
@@ -2780,6 +2876,10 @@ function parseOptions(argv) {
             yes: values.yes,
             from: values.from,
             since: values.since,
+            until: values.until,
+            sku: values.sku,
+            tool: values.tool,
+            cursor: values.cursor,
             to: values.to,
             grain: values.grain,
             channel: values.channel,
@@ -2846,6 +2946,15 @@ 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";
+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))
@@ -3391,8 +3500,44 @@ async function readImportFile(path) {
     return readFile(path);
 }
 const ASSET_ROUTE = "/api/v1/assets/";
-/** What `creatives download` fetches, from a SKU, an asset path, or an asset link as `creatives show` prints it. */
+/** Saves a creative's or a made output's file, as `creatives download` and `media download` do. */
+async function download(arg, options) {
+    const connection = await resolveConnection(options);
+    const target = await downloadTarget(arg, connection);
+    const { bytes, contentType } = await apiDownload(connection, `${ASSET_ROUTE}${target.assetPath.split("/").map(encodeURIComponent).join("/")}`);
+    const path = await savePath(options.out, extname(target.fileName) ? target.fileName : `${target.fileName}.${extensionFor(contentType)}`);
+    await saveFile(path, bytes);
+    if (options.open)
+        openFile(resolve(path));
+    if (options.format === "json")
+        return printJson({ path: resolve(path), bytes: bytes.byteLength, contentType });
+    console.log(`Saved ${target.label} to ${path} (${fileSize(bytes.byteLength)}).`);
+}
+const MEDIA_ID = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}):(0|[1-9]\d{0,3})$/i;
+function parseMediaId(raw) {
+    const match = MEDIA_ID.exec(raw);
+    return match ? { runId: match[1].toLowerCase(), index: Number(match[2]) } : null;
+}
+// A media id's colon is sent as it is, so the route reads the id whether or not the server decodes the path.
+function mediaPath(raw) {
+    const id = parseMediaId(raw);
+    if (!id)
+        throw new CliError(`"${excerpt(raw)}" is not a media id; media list prints them as <run id>:<index>.`, exitCodes.usage);
+    return `/api/v1/media/${id.runId}:${id.index}`;
+}
+function costLabel(media) {
+    return `${media.costCents}¢${media.costIsEstimate ? " (estimate)" : ""}`;
+}
+/** What `creatives download` fetches, from a SKU, a media id, an asset path, or an asset link as `creatives show` prints it. */
 async function downloadTarget(arg, connection) {
+    const output = parseMediaId(arg);
+    if (output) {
+        const { media } = await api(connection, mediaPath(arg));
+        if (!media.assetPath)
+            throw new CliError(`${media.id} has no stored file to download.`, exitCodes.error);
+        const name = media.sku ?? `${output.runId}-${output.index}`;
+        return { label: media.sku ?? media.id, assetPath: media.assetPath, fileName: `${name}${extname(media.assetPath)}` };
+    }
     const routeAt = arg.indexOf(ASSET_ROUTE);
     if (routeAt !== -1 || arg.includes("/")) {
         const assetPath = routeAt === -1 ? arg : decodeLinkPath(arg.slice(routeAt + ASSET_ROUTE.length).replace(/[?#].*$/, ""));

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.45",
+  "version": "0.3.47",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {