@flowapt/flowiq-cli 0.3.1 → 0.3.3

package/README.md

@@ -187,9 +187,15 @@ flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
   leading-zero handled). The mapper auto-suggests from the template's
   semantic labels + body text and you confirm each slot once; the mapping is
   saved to `.flowiq/campaigns/<campaign>.json` and reused.
-- **v1 scope**: Meta orgs, POSITIONAL templates, text/no header. NAMED,
-  carousel, media-header templates and WATI orgs are refused with a clear
-  message.
+- **Media-header templates (image/video/document) ARE supported** (v0.3.3) —
+  exactly like the dashboard. The header image defaults to the template's own
+  stored image (`template_data.header.default_url`); override with
+  `--header-media <public-url>` on `map`/`preview`/`send`. Passed to
+  `/api/send-template` as `headerMedia`, the same field the dashboard uses. A
+  media-header template with no resolvable image is refused (pass
+  `--header-media`).
+- **v1 scope**: Meta orgs, POSITIONAL templates, text / no header / media header.
+  NAMED and carousel templates and WATI orgs are refused with a clear message.
 - **Validation before anything sends**: APPROVED-only, every slot mapped,
   contiguous params (the Meta `#132000` guard — a stray key is structurally
   impossible), phone validity, illegal characters (Meta `#100`; `reject` by
@@ -238,6 +244,14 @@ flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_tru
 # as `tag attributes --filter`). --split N (2..100) replaces --batch-size;
 # --seed makes the shuffle reproducible, --ordered keeps server order (no shuffle).
 
+# Cohort from EXISTING TAGS → batched (v0.3.2 — combine tags, then split, no id file):
+flowiq seg plan <org_id> --tag-prefix 18-july-clearance-bc \
+  --from-tag "9-jul-loyalty-list" --exclude "recent-campaign,opt-out" --batch-size 1000
+# contacts carrying ANY of the --from-tag tags, MINUS anyone carrying any --exclude
+# tag, minus archived/blocked/opted-out → sliced into 1000-sized batch tags
+# (18-july-clearance-bc-batch-01, -02, …). --from-tag pairs with --split too.
+# This is the "existing tags → batched send list" flow, entirely in the CLI.
+
 # Cohort by ORDER-COUNT CRITERIA (v0.2.6 — server-resolved, no id file needed):
 flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d
 # "everyone with 2+ orders in the last 60 days" — counted from the captured
@@ -262,11 +276,13 @@ flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own ta
 
 - **Cohort sources:** `--from-attribute <filter>` (a broadcast-permission
   audience — `all_contacts` / `allow_broadcast_true` / `allow_broadcast_false`
-  / `no_broadcast_permission`, resolved server-side past the 1000-row cap);
-  `--min-orders [--window]` (the windowed order count the app's Advanced Tagging
-  UI cannot express — its Min Orders filter is lifetime-only); `--bought`
-  (product line-items); or explicit **contact UUIDs** (a snapshot JSON's
-  `contact_ids[]` or a plain file). Exactly one per plan.
+  / `no_broadcast_permission`, resolved server-side in one RPC call);
+  **`--from-tag "a,b" [--exclude "c,d"]`** (contacts carrying ANY of the include
+  tags minus anyone carrying an exclude tag — the "existing tags → batched send
+  list" source, v0.3.2); `--min-orders [--window]` (the windowed order count the
+  app's Advanced Tagging UI cannot express — its Min Orders filter is
+  lifetime-only); `--bought` (product line-items); or explicit **contact UUIDs**
+  (a snapshot JSON's `contact_ids[]` or a plain file). Exactly one per plan.
 - **`--split N` = exactly N even cohorts** (2..100), an alternative to
   `--batch-size` fixed chunks. It **shuffles by default** so the cohorts are
   balanced (not skewed by contact age / signup order); `--seed S` makes the

package/TEAM-GUIDE.md

@@ -88,8 +88,10 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Advanced Tagging in the terminal (one named tag on a matched set) | `flowiq tag field\|cohort\|segment\|attributes\|messages <org_id> …` (dry-run) → add `--tag <name> --commit` |
 | List / remove tags | `flowiq tag list <org_id>` · `flowiq tag remove <org_id> <tag> --confirm` |
 | Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
+| Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` |
+| Send a broadcast whose template has an IMAGE header | Same as above — the image is automatic (the template's own header image). Override with `--header-media <public-image-url>` if needed. |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/broadcast.js

@@ -335,12 +335,17 @@ async function introspect(orgId, templateName) {
 }
 
 /** Validation V-1..V-13. Returns {valid, skipped, aborts}. */
-function validateRows(template, mapping, headers, rows, illegalChars) {
+function validateRows(template, mapping, headers, rows, illegalChars, headerMedia) {
   const aborts = [];
   if (template.status !== "APPROVED") aborts.push(`V-1: template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("V-2: NAMED templates are not supported in v1");
   if (template.is_carousel) aborts.push("V-3: carousel templates are not supported in v1");
-  if (!["text", "none"].includes(template.header_type)) aborts.push(`V-3: media-header templates (${template.header_type}) are not supported in v1`);
+  // Media headers (image/video/document) ARE supported — they just need an image
+  // URL, exactly like the dashboard. Resolved as --header-media / saved mapping /
+  // the template's stored default_url. Only block if a media header has none.
+  if (!["text", "none"].includes(template.header_type) && !headerMedia) {
+    aborts.push(`V-3: template has a ${template.header_type} header but no image resolved — pass --header-media <url> (the template has no stored default header image)`);
+  }
   for (const pos of template.body_positions) {
     if (!mapping.body_params?.[`param${pos}`]?.source) aborts.push(`V-4: body param${pos} is unmapped`);
   }
@@ -428,12 +433,13 @@ async function applySafetyExclusions(orgId, valid, skipped) {
   return keep;
 }
 
-function renderPreview(template, sample) {
+function renderPreview(template, sample, headerMedia) {
   let bodyText = template.body_text;
   for (const [k, v] of Object.entries(sample.values)) {
     bodyText = bodyText.replaceAll(`{{${k.replace("param", "")}}}`, v);
   }
   console.log(`Row ${sample.rownum}  →  ${sample.number}   [VALID]${sample.sanitized ? " (sanitized)" : ""}`);
+  if (headerMedia) console.log(`  Header (${template.header_type}): ${headerMedia}`);
   console.log(`  Body:\n    ${bodyText.replace(/\n/g, "\n    ")}`);
   if (template.url_button?.present && sample.buttonValue != null) {
     const url = template.url_button.url_base.replace(/\{\{[^}]+\}\}/, sample.buttonValue);
@@ -472,7 +478,7 @@ function classifySendError(errText) {
   return "row_fatal";
 }
 
-async function sendOne(apiUrl, orgId, templateName, row) {
+async function sendOne(apiUrl, orgId, templateName, row, headerMedia) {
   // #132000 structural guard: whitelist param\d+ keys only.
   const bodyParameters = {};
   for (const [k, v] of Object.entries(row.values)) {
@@ -484,6 +490,9 @@ async function sendOne(apiUrl, orgId, templateName, row) {
     whatsappNumber: row.number,
     bodyParameters,
     ...(row.buttonValue != null ? { buttonParameters: { param1: row.buttonValue } } : {}),
+    // Static media header (same field the dashboard passes for image/video/doc
+    // headers) — /api/send-template renders it onto the HEADER component.
+    ...(headerMedia ? { headerMedia } : {}),
   };
   // Org-UUID branch: NO auth header (a staff key here would 401 on the fiq_ branch).
   const resp = await fetch(`${apiUrl.replace(/\/$/, "")}/send-template?organizationId=${orgId}`, {
@@ -517,7 +526,14 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   try { intro = await introspect(orgId, templateName); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   const template = intro.template;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  // Media-header templates send a static image (frontend behaviour): prefer an
+  // explicit --header-media, then a previously-saved one, then the template's
+  // stored default_url. Non-media headers → null.
+  const isMediaHeader = !["text", "none"].includes(template.header_type);
+  const headerMedia = isMediaHeader
+    ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
+    : null;
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerMedia ? " (image ✓)" : ""}${template.url_button?.present ? ", dynamic URL button" : ""}`);
 
   // 4. CSV
   let csv;
@@ -550,6 +566,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
       recipient: built.recipient,
       body_params: built.body_params,
       button_params: built.button_params,
+      ...(headerMedia ? { header_media: headerMedia } : {}),
       options: { illegal_chars: opts.illegalChars || "reject" },
     };
     await saveCampaign(cfg);
@@ -558,7 +575,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   }
 
   // 6. validate
-  const { aborts, valid, skipped } = validateRows(template, mapping, csv.headers, csv.rows, opts.illegalChars || mapping.options?.illegal_chars || "reject");
+  const { aborts, valid, skipped } = validateRows(template, mapping, csv.headers, csv.rows, opts.illegalChars || mapping.options?.illegal_chars || "reject", headerMedia);
   if (aborts.length) { for (const a of aborts) console.error(`ABORT — ${a}`); process.exit(1); }
 
   // 6b. broadcast-safety exclusions (live)
@@ -590,7 +607,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log("");
   const nPreview = Math.max(1, Number(opts.rows ?? 3));
   const samples = [sendable[0], ...sendable.slice(1).filter((r, i, a) => a.findIndex((x) => x.values.param1 === r.values.param1) === i)].filter(Boolean).slice(0, nPreview);
-  for (const s of samples) { renderPreview(template, s); console.log(""); }
+  for (const s of samples) { renderPreview(template, s, headerMedia); console.log(""); }
   console.log(`Summary: ${sendable.length} sendable · skipped ${skipped.length} (${Object.entries(skippedByReason).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`);
   if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
   if (ambiguous.length) console.log(`⚠ ${ambiguous.length} number(s) have an AMBIGUOUS in-flight status (crash mid-send?) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}. Check the chat, then edit the status log if they must be retried.`);
@@ -620,7 +637,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
 
   // 10-11. send loop + report (shared with the --tag pipeline)
   await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate,
+    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
     skippedCount: skipped.length,
     writeMetaHeader: !logHeader,
     metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
@@ -628,7 +645,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */
-async function executeSendLoop({ orgId, campaign, templateName, workSet, statusMap, rate, skippedCount, writeMetaHeader, metaExtras }) {
+async function executeSendLoop({ orgId, campaign, templateName, workSet, statusMap, rate, skippedCount, writeMetaHeader, metaExtras, headerMedia }) {
   const { api_url } = await loadConfig();
   if (writeMetaHeader) {
     await appendLog(campaign, {
@@ -648,7 +665,7 @@ async function executeSendLoop({ orgId, campaign, templateName, workSet, statusM
       // WRITE-AHEAD: sending line BEFORE the POST.
       await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "sending", attempt, at: new Date().toISOString() });
       let out;
-      try { out = await sendOne(api_url, orgId, templateName, row); }
+      try { out = await sendOne(api_url, orgId, templateName, row, headerMedia); }
       catch (e) {
         // network/timeout with no response = UNKNOWN outcome → ambiguous, never auto-retried
         await appendLog(campaign, { type: "row", number: row.number, rownum: row.rownum, status: "unknown", error: e.message, attempt, at: new Date().toISOString() });
@@ -730,12 +747,17 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   try { intro = await introspect(orgId, templateName); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   const template = intro.template;
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  const isMediaHeader = !["text", "none"].includes(template.header_type);
+  const headerMedia = isMediaHeader
+    ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
+    : null;
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerMedia ? " (image ✓)" : ""}${template.url_button?.present ? ", dynamic URL button" : ""}`);
   const aborts = [];
   if (template.status !== "APPROVED") aborts.push(`template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("NAMED templates are not supported in v1");
   if (template.is_carousel) aborts.push("carousel templates are not supported in v1");
-  if (!["text", "none"].includes(template.header_type)) aborts.push(`media-header templates (${template.header_type}) are not supported in v1`);
+  // Media headers supported — need an image (--header-media / saved / default_url).
+  if (isMediaHeader && !headerMedia) aborts.push(`template has a ${template.header_type} header but no image resolved — pass --header-media <url> (the template has no stored default header image)`);
   const keys = Object.keys(bodyLiterals);
   if (keys.some((k) => !/^param\d+$/.test(k))) aborts.push(`--body keys must be param1..N (got ${keys.join(", ")})`);
   if (keys.length !== template.body_var_count) aborts.push(`template expects ${template.body_var_count} body param(s), you provided ${keys.length} (--body paramN=…). Values may use {{first_name}}/{{full_name}}/{{email}}/{{phone_number}} — resolved per contact.`);
@@ -769,7 +791,7 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   });
 
   console.log("");
-  renderPreview(template, sendable[0]);
+  renderPreview(template, sendable[0], headerMedia);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens above are resolved PER CONTACT server-side)");
   }
@@ -799,11 +821,12 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     organization_id: orgId, organization_slug: slugify(resolved.organization_name, orgId.slice(0, 8)),
     template_name: templateName, tag,
     body_params_literal: bodyLiterals, button_param_literal: buttonLiteral,
+    ...(headerMedia ? { header_media: headerMedia } : {}),
     created_at: cfg?.created_at ?? new Date().toISOString(),
   });
 
   await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate,
+    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
     skippedCount: resolved.excluded.length,
     writeMetaHeader: !logHeader,
     metaExtras: { tag, tagged_total: resolved.tagged_total, valid_rows: sendable.length },
@@ -829,6 +852,12 @@ export async function map(orgId, opts = {}) {
     return;
   }
   const built = await interactiveMapping(intro.template, csv.headers, campaign);
+  const t = intro.template;
+  const headerMedia = !["text", "none"].includes(t.header_type)
+    ? (opts.headerMedia || t.header_media_default || null) : null;
+  if (!["text", "none"].includes(t.header_type)) {
+    console.log(headerMedia ? `Header image (${t.header_type}): ${headerMedia}` : `⚠ ${t.header_type} header but no image — pass --header-media <url> on send.`);
+  }
   await saveCampaign({
     schema_version: 1, campaign, organization_id: orgId,
     organization_slug: slugify(intro.organization_name, orgId.slice(0, 8)),
@@ -836,6 +865,7 @@ export async function map(orgId, opts = {}) {
     created_at: new Date().toISOString(),
     csv: { path: opts.csv, delimiter: csv.delimiter, headers: csv.headers, header_fingerprint: csv.header_fingerprint },
     recipient: built.recipient, body_params: built.body_params, button_params: built.button_params,
+    ...(headerMedia ? { header_media: headerMedia } : {}),
     options: { illegal_chars: "reject" },
   });
   console.log(`Saved mapping: ${cfgPath(campaign)}`);

package/src/commands/segments.js

@@ -3,8 +3,9 @@
 // runbook). This command TAGS ONLY — it never sends. The send per tag is
 // `flowiq broadcast send --tag <batch-tag>` (or the dashboard broadcaster).
 //
-//   plan  <org> --tag-prefix X (--from-segment file | --ids-file file
-//                               | --min-orders N [--window 60d])        # exclusions → slice → plan file (no DB write)
+//   plan  <org> --tag-prefix X (--from-attribute F | --from-tag "a,b" [--exclude "c,d"]
+//                               | --min-orders N [--window 60d] | --bought "P"
+//                               | --from-segment file | --ids-file file)  # exclusions → slice → plan file (no DB write)
 //   apply <org> <slug>  [--commit] [--yes]                              # append the batch tags (dry-run default)
 //   list  <org> [--prefix X]                                            # VERIFY: tag → contact count
 //   untag <org> <slug> --commit --confirm                               # ROLLBACK: remove the plan's own tags
@@ -132,18 +133,20 @@ export async function plan(orgId, opts = {}) {
     if (opts.seed !== undefined && !Number.isFinite(Number(opts.seed))) { console.error("Error: --seed must be a number."); process.exit(1); }
   }
 
-  // Cohort source: a server-resolved criterion (--from-attribute / --min-orders
-  // / --bought) OR an explicit id list (--from-segment / --ids-file). Exactly one.
+  // Cohort source: a server-resolved criterion (--from-attribute / --from-tag /
+  // --min-orders / --bought) OR an explicit id list (--from-segment / --ids-file).
+  // Exactly one.
   const orderMode = opts.minOrders !== undefined;
   const productMode = opts.bought !== undefined;
   const attributeMode = opts.fromAttribute !== undefined;
-  const criteriaMode = orderMode || productMode || attributeMode;
-  const sourceCount = [orderMode, productMode, attributeMode, !!opts.fromSegment, !!opts.idsFile].filter(Boolean).length;
+  const tagMode = opts.fromTag !== undefined;
+  const criteriaMode = orderMode || productMode || attributeMode || tagMode;
+  const sourceCount = [orderMode, productMode, attributeMode, tagMode, !!opts.fromSegment, !!opts.idsFile].filter(Boolean).length;
   if (sourceCount === 0) {
-    console.error("Error: a cohort source is required — one of --from-attribute / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
+    console.error("Error: a cohort source is required — one of --from-attribute / --from-tag / --min-orders / --bought / --from-segment / --ids-file."); process.exit(1);
   }
   if (sourceCount > 1) {
-    console.error("Error: pick exactly ONE cohort source (--from-attribute / --min-orders / --bought / --from-segment / --ids-file)."); process.exit(1);
+    console.error("Error: pick exactly ONE cohort source (--from-attribute / --from-tag / --min-orders / --bought / --from-segment / --ids-file)."); process.exit(1);
   }
 
   let cohort;
@@ -157,6 +160,12 @@ export async function plan(orgId, opts = {}) {
       }
       cohortSpec = { attribute };
       cohort = { ids: [], badUuids: [], sourceMeta: { type: "attribute_cohort", attribute } };
+    } else if (tagMode) {
+      const includeTags = String(opts.fromTag).split(",").map((s) => s.trim()).filter(Boolean);
+      if (!includeTags.length) { console.error("Error: --from-tag needs at least one tag (comma-separate several)."); process.exit(1); }
+      const excludeTags = opts.exclude ? String(opts.exclude).split(",").map((s) => s.trim()).filter(Boolean) : [];
+      cohortSpec = { include_tags: includeTags, exclude_tags: excludeTags };
+      cohort = { ids: [], badUuids: [], sourceMeta: { type: "tag_cohort", include_tags: includeTags, exclude_tags: excludeTags } };
     } else {
     let windowDays = null;
     if (opts.window) {
@@ -209,6 +218,10 @@ export async function plan(orgId, opts = {}) {
         no_broadcast_permission: "contacts with no broadcast permission set",
       }[resp.cohort.attribute] || resp.cohort.attribute;
       console.log(`Cohort: ${label} → ${resp.cohort.resolved_count} contact(s) (server-resolved).`);
+    } else if (resp.cohort.kind === "tag") {
+      const inc = resp.cohort.include_tags.join(", ");
+      const exc = resp.cohort.exclude_tags && resp.cohort.exclude_tags.length ? `, excluding [${resp.cohort.exclude_tags.join(", ")}]` : "";
+      console.log(`Cohort: contacts tagged any of [${inc}]${exc} → ${resp.cohort.resolved_count} contact(s) (server-resolved).`);
     } else {
       const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
       if (resp.cohort.kind === "product") {

package/src/index.js

@@ -371,6 +371,7 @@ export function run(argv) {
     .requiredOption("--template <name>", "approved Meta template name")
     .requiredOption("--csv <file>", "path to the recipients CSV")
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename)")
+    .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
     .action((orgId, opts) => broadcastCmd.map(orgId, opts));
   broadcast.command("preview <organization_id>")
@@ -378,6 +379,7 @@ export function run(argv) {
     .option("--template <name>", "template (default: from the saved campaign)")
     .option("--csv <file>", "CSV (default: from the saved campaign)")
     .option("--campaign <name>", "campaign id / config file slug")
+    .option("--header-media <url>", "override the media-header image URL (default: the template's stored image)")
     .option("--rows <n>", "how many sample rows to render", "3")
     .action((orgId, opts) => broadcastCmd.preview(orgId, opts));
   broadcast.command("send <organization_id>")
@@ -388,6 +390,7 @@ export function run(argv) {
     .option("--body <k=v>", "with --tag: body param (repeatable), e.g. --body param1=\"Hi {{first_name}}\"", broadcastCmd.collectKV, {})
     .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
+    .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
     .option("--commit", "actually send (omit to dry-run)")
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
@@ -421,6 +424,8 @@ export function run(argv) {
     .option("--from-segment <path>", "a segments snapshot JSON (uses its contact_ids[])")
     .option("--ids-file <path>", "a plain newline/CSV file of contact UUIDs")
     .option("--from-attribute <filter>", "SERVER-RESOLVED cohort: every contact matching a broadcast-permission filter (all_contacts | allow_broadcast_true | allow_broadcast_false | no_broadcast_permission)")
+    .option("--from-tag <csv>", "SERVER-RESOLVED cohort: contacts carrying ANY of these tag(s) (comma-separated)")
+    .option("--exclude <csv>", "with --from-tag: drop contacts carrying ANY of these tag(s)")
     .option("--min-orders <n>", "SERVER-RESOLVED cohort: contacts with ≥ n captured orders (instead of an id file)")
     .option("--bought <terms>", "SERVER-RESOLVED cohort: contacts who bought these product(s) (comma-separated name substrings) from real order line-items")
     .option("--match <mode>", "with --bought: any (bought any listed product) | all (bought every one)", "any")