@wrangled/cli 0.3.11 → 0.3.13

package/dist/guide.js

@@ -166,6 +166,14 @@ Kinds are \`exclusion\`, \`gap\`, \`baseline\`, \`change\`, \`definition\`, \`ca
 
 To suggest a fact, write it as JSON and run \`${cli} facts propose --file fact.json\` (or pipe it on stdin): \`{"kind": "gap", "subject_type": "table", "subject_ref": "meta_insights_daily", "key": "history_start", "value": {"table": "meta_insights_daily", "from": "2026-04-07"}, "summary": "Facebook ad numbers only go back to April 7, 2026.", "evidence": {"query": "SELECT min(date) FROM meta_insights_daily"}}\`. You only suggest: a person confirms, fixes or rejects it in the app. A fact with the same kind, subject and key already open is refused as \`fact_exists\`. Evidence is counts, queries and ids, never names, emails or phones.
 
+## Ad tags
+
+Ads not made here (built by hand or by an agency, names in no pattern) get the marketing grammar's tags (docs/marketing-grammar.md) by Meta ad id. \`${cli} ads tags\` lists them (\`--ad <id>\`, \`--status proposed|confirmed|rejected|replaced\`, \`--limit <n>\`, \`--json\`); by default the live ones, proposed and confirmed. A proposed tag is usable at once, but not yet confirmed; only an Owner or Admin confirms, rejects or changes tags, in the app.
+
+To suggest tags, write them as JSON and run \`${cli} ads tag --file tags.json\` (or pipe it on stdin), up to 500 ads at a time: \`{"ads": [{"ad_id": "120214567890123", "tags": {"angle": "discovery", "desire": "money", "hook_spot": "spoken", "hook_text": "$29,000 is the smallest lead", "hook_kind": "big_win", "format": "video", "style": "presenter", "tag_reasons": {"worry": "none"}}, "confidence": "medium", "evidence": {"ad_name": "County lead v2", "transcript_start": "$29,000 is the smallest lead"}}]}\`. The tag fields are \`marketing\`, \`offer_key\`, \`landing_funnel_key\`, \`landing_step_key\`, \`persona\`, \`awareness\`, \`concept\`, \`angle\`, \`desire\`, \`hook_spot\`, \`hook_text\`, \`hook_kind\`, \`hook2_spot\`, \`hook2_kind\`, \`format\`, \`style\`, \`speaker\`, \`cta\`, \`proof\` and \`worry\`; leave out what you did not judge. A part with no value goes in \`tag_reasons\` as \`none\` (nothing on its list applies) or \`unclear\` (too little to judge, never \`high\` confidence). Confidence is \`high\`, \`medium\` or \`low\`. A value off its list is refused with the allowed values. New tags replace an ad's proposed ones, which stay as \`replaced\`; an ad whose tags a person confirmed is kept as it is.
+
+For what worked, query the \`ad_performance_tagged\` view: every Meta ad's daily results with its live tags next to them, \`tags_source\` (\`ad_tags\`, or null when untagged) and \`tags_status\`.
+
 ## What customers keep saying
 
 Every hour an AI reads the workspace's new Facebook and Instagram comments, Google reviews and Reddit posts and comments, pulls out openers (lines that would open an ad), objections (why people hesitate) and phrases (customers' own words for their problem or result), and groups the ones that say the same thing. Names, emails, phone numbers and handles are taken out first. \`${cli} voice\` lists the groups, most common first (\`--kind opener|objection|phrase\`, \`--limit <n>\` up to 200, \`--json\`), each with how many rows said it, their likes, and up to 3 real quotes. In \`--json\`, each quote's \`{kind, ref, quote}\` goes straight into a creative's \`researchSources\`, and a group itself can be cited as its \`ref\`, \`voice_clusters:<id>\`. The same rows are in the \`voice_clusters\` and \`voice_insights\` tables.
@@ -272,6 +280,7 @@ ${cli} funnels evidence   prices paid, buyer paths, GoHighLevel funnels, calenda
 ${cli} funnels draft --file <map.json> [--note <why>] [--evidence '<json>' | @file.json] [--based-on <n>] [--counts-from fix|<date>] [--questions @file.json]   save the whole map; it goes live when every step can be counted
 ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--json] | facts show <id>   settled facts about the data, to treat as true
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
+${cli} ads tags [--ad <id>] [--status <status>] [--limit <n>] | ads tag --file <tags.json>   the marketing tags of ads not made here, and suggesting them
 ${cli} voice [--kind opener|objection|phrase] [--limit <n>] [--json]   what customers keep saying, grouped and counted, with real quotes
 ${cli} voice lists                  where that voice comes from: the competitors whose ads, and the subreddits and Reddit search phrases whose posts, are saved, and suggestions waiting
 ${cli} voice suggest competitor|subreddit|search_phrase "<value>" [--note <why>]   suggest a competitor, subreddit or Reddit search phrase for a person to approve

package/dist/main.js

@@ -1027,12 +1027,16 @@ const commands = {
             const counts = options.countsFrom === undefined || options.countsFrom === "fix" ? "it counts for past dates too, as a fix" : `it counts from ${options.countsFrom}, as a change`;
             console.log(saved.applied
                 ? `Map version ${saved.version.version} is live${based}: ${counts}. A person can undo it in the app.`
-                : `Saved version ${saved.version.version}${based}. It is on hold: it counts nothing until every step can be counted.`);
+                : saved.held === "undone_by_person"
+                    ? `Saved version ${saved.version.version}${based}. It is on hold: it counts nothing until a person puts it live.`
+                    : `Saved version ${saved.version.version}${based}. It is on hold: it counts nothing until every step can be counted.`);
             if (saved.reapplied.length > 0)
                 console.log(`\nAnswers put back into the map: ${saved.reapplied.join(", ")}`);
             if (saved.asked.length > 0)
                 console.log(`\nQuestions open for a person, biggest money at stake first: ${saved.asked.join(", ")}`);
-            const [left, warnings] = [saved.warnings.filter((w) => w.message.startsWith("question ")), saved.warnings.filter((w) => !w.message.startsWith("question "))];
+            const [left, warnings] = [saved.warnings.filter((w) => w.message.startsWith("question ")), saved.warnings.filter((w) => !w.message.startsWith("question ") && w.path !== "")];
+            for (const w of saved.warnings.filter((w) => w.path === ""))
+                console.log(`\n${w.message}`);
             if (warnings.length > 0)
                 console.log(`\n${saved.applied ? "Not in synced data yet" : "To fill in"}:\n${warnings.map((w) => `- ${w.path}: ${w.message}`).join("\n")}`);
             if (left.length > 0)
@@ -1117,6 +1121,39 @@ const commands = {
             console.log(renderTable(VOICE_COLUMNS, clusters.map(voiceRow)));
         },
     },
+    "ads tags": {
+        usage: "ads tags [--ad <id>] [--status <status>] [--limit <n>] [--json]   the marketing tags of ads not made here, by Meta ad id",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: ads tags [--ad <id>] [--status <status>] [--limit <n>] [--json]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.ad)
+                query.set("ad", options.ad);
+            if (options.status)
+                query.set("status", options.status);
+            if (options.limit)
+                query.set("limit", options.limit);
+            const { tags } = await api(await resolveConnection(options.apiUrl), `${AD_TAGS_PATH}${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ tags });
+            if (tags.length === 0)
+                return console.log("No ad tags.");
+            console.log(renderTable(AD_TAG_COLUMNS, tags.map(adTagRow)));
+        },
+    },
+    "ads tag": {
+        usage: "ads tag --file <tags.json> | < tags.json   suggest tags for up to 500 ads; a person confirms them in the app",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: ads tag --file <tags.json> | < tags.json", exitCodes.usage);
+            const result = await api(await resolveConnection(options.apiUrl), AD_TAGS_PATH, await readToolInput(options));
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Proposed tags for ${result.proposed.length} ${result.proposed.length === 1 ? "ad" : "ads"}. A person confirms or rejects them in the app.`);
+            if (result.kept.length > 0)
+                console.log(`Kept as they are, since a person confirmed their tags: ${result.kept.map((k) => k.adId).join(", ")}.`);
+        },
+    },
     "facts show": {
         usage: "facts show <id>   one fact with its value and evidence",
         async run(args, options) {
@@ -1618,6 +1655,8 @@ function printReport(title, report, labels, numbers) {
 }
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
 const FACTS_PATH = "/api/v1/facts";
+const AD_TAGS_PATH = "/api/v1/ad-tags";
+const AD_TAG_COLUMNS = ["id", "ad", "status", "confidence", "offer", "persona", "angle", "hook", "format", "author"];
 const VOICE_LISTS_PATH = "/api/v1/voice-lists";
 const VOICE_SUGGESTIONS_PATH = "/api/v1/voice-lists/suggestions";
 const FACT_COLUMNS = ["id", "kind", "subject", "key", "status", "summary"];
@@ -1632,6 +1671,10 @@ function knowledgeBlock(r, i) {
         lines.push(`   Caveat: ${r.caveat}`);
     return lines.join("\n");
 }
+function adTagRow(t) {
+    const { offer_key, persona, angle, hook_kind, hook_spot, format, style } = t.tags;
+    return { id: t.id, ad: t.adId, status: t.status, confidence: t.confidence, offer: offer_key, persona, angle, hook: [hook_kind, hook_spot].filter(Boolean).join(" in ") || null, format: [format, style].filter(Boolean).join(", ") || null, author: t.author };
+}
 function voiceRow(c) {
     return { ref: c.ref, kind: c.kind, "said by": c.supportCount, likes: c.likeSum, label: excerpt(c.label, 60), "top quote": c.evidence[0] ? excerpt(c.evidence[0].quote, 60) : null };
 }
@@ -1747,7 +1790,8 @@ 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 and voice return
+  --limit <n>           how many results content search, creatives list, campaigns, voice and ads tags return
+  --ad <id>             with ads tags, only this Meta ad's tags
   --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
   -h, --help            show this help
@@ -1777,6 +1821,7 @@ function parseOptions(argv) {
             wait: { type: "string", default: String(DEFAULT_WAIT_SECONDS) },
             status: { type: "string" },
             kind: { type: "string" },
+            ad: { type: "string" },
             limit: { type: "string" },
             run: { type: "string" },
             lineage: { type: "string" },
@@ -1867,6 +1912,7 @@ function parseOptions(argv) {
             wait,
             status: values.status,
             kind: values.kind,
+            ad: values.ad,
             limit: values.limit,
             run: values.run,
             lineage: values.lineage,

package/package.json

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