@wrangled/cli 0.3.45 → 0.3.46

package/dist/guide.js

@@ -140,6 +140,7 @@ 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 }\`.
 
 ## Landing pages
 
@@ -326,9 +327,12 @@ ${cli} tools run <tool> --input '<json>' [--idempotency-key <key>] [--wait <seco
 ${cli} tools get <run-id>           show a tool run, waiting for it to finish (--wait)
 ${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

@@ -545,20 +545,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 +582,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 +2572,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
@@ -2568,7 +2601,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), 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 +2640,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 +2709,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 +2824,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,
@@ -3391,8 +3439,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/package.json

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