@flowapt/flowiq-cli 0.2.6 → 0.2.7

package/README.md

@@ -236,6 +236,12 @@ flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d
 # order stores (shopify_orders/woo_orders), NOT the lifetime orders_count column.
 # --window takes 60d / 8w / 3m; omit it for all captured history. --platform auto|shopify|woo.
 
+# Cohort by PRODUCT PURCHASE (v0.2.7 — from real order line-items):
+flowiq seg plan <org_id> --tag-prefix whey --bought "Protein Water,Whey" --window 90d
+# contacts who bought any of these products (name substrings) in the window;
+# --match all (bought every listed product), --min-purchases 2 (bought 2+ times).
+# More accurate than the app's Field Search on order_history text (which drifts).
+
 # Cohort by explicit id list (the original mode):
 flowiq seg plan <org_id> --tag-prefix july-promo --ids-file ./cohort.txt   # or --from-segment snapshot.json
 
@@ -257,6 +263,47 @@ flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own ta
   `plan` to refresh it (someone who ordered since won't auto-drop, criteria
   mode included).
 
+### Advanced Tagging — `flowiq tag field|cohort|segment|attributes|messages|list|remove`
+
+The **Contacts → Advanced Tagging** dialog in the terminal — applies **one
+named tag** to a matched set of contacts (not batch tags; that's `segments`).
+Every match mode is **dry-run by default** (prints the count + a sample); add
+`--tag <name> --commit` to write. Appends only — it never touches a contact's
+other tags. Runs through the staff-gated **service role**, so it's immune to
+the anon exposure the in-app RPCs carry.
+
+```bash
+# Field search — keyword(s) in a field (order_history/contact_summary/shopify_tags/full_name/email/…)
+flowiq tag field <org_id> --field order_history --any "Protein Water,Whey"          # dry-run
+flowiq tag field <org_id> --field shopify_tags --any "VIP" --tag vip --commit
+
+# Cohort — top-N ranking (top_spenders / frequent_buyers / recent_buyers / high_value_low_frequency)
+flowiq tag cohort <org_id> --type top_spenders --limit 500 --tag top-500 --commit
+
+# Custom segment — order-count / spend / last-order-date / region / keyword filters
+flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP --tag gp-repeat --commit
+
+# Attributes — broadcast permission (all_contacts / allow_broadcast_true|false / no_broadcast_permission)
+flowiq tag attributes <org_id> --filter allow_broadcast_true --tag broadcastable --commit
+
+# Message activity — ≥ N messages of a sender type, optional date range
+flowiq tag messages <org_id> --min-count 3 --sender user-whatsapp --tag engaged --commit
+
+flowiq tag list   <org_id>                          # tags + counts (read-only)
+flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL contacts (destructive)
+```
+
+- **Dry-run first, always.** Without `--commit` you get the match count + a
+  10-row sample and nothing writes. A commit over 2000 contacts asks you to
+  type the tag name (skip with `--yes`).
+- **`field` reads the `order_history` TEXT** (which can drift from the real
+  orders). For accurate "who bought product X", prefer
+  `flowiq seg plan --bought "X"` (real order line-items, windowable).
+- **`cohort` is top-N, not a threshold** — `top_spenders --limit 500` tags the
+  top 500 by spend, not "everyone above £X". Use `tag segment --min-spent` for
+  a threshold.
+- **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
+
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
 
 Round-trips an org's **keyword auto-reply engine** — the `keywords` +

package/TEAM-GUIDE.md

@@ -77,6 +77,9 @@ you have installed.
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
+| Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
+| 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 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` |
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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/segments.js

@@ -102,26 +102,44 @@ export async function plan(orgId, opts = {}) {
   if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
   if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
 
-  // Cohort source: a server-resolved order-count criterion (--min-orders
-  // [--window]) OR an explicit id list (--from-segment / --ids-file).
-  const criteriaMode = opts.minOrders !== undefined;
+  // Cohort source: a server-resolved criterion (--min-orders OR --bought,
+  // both with an optional --window) OR an explicit id list (--from-segment /
+  // --ids-file).
+  const orderMode = opts.minOrders !== undefined;
+  const productMode = opts.bought !== undefined;
+  const criteriaMode = orderMode || productMode;
+  if (orderMode && productMode) {
+    console.error("Error: use either --min-orders or --bought, not both."); process.exit(1);
+  }
   if (criteriaMode && (opts.fromSegment || opts.idsFile)) {
-    console.error("Error: --min-orders cannot be combined with --from-segment / --ids-file.");
-    process.exit(1);
+    console.error("Error: --min-orders / --bought cannot be combined with --from-segment / --ids-file."); process.exit(1);
   }
 
   let cohort;
   let cohortSpec = null;
   if (criteriaMode) {
-    const minOrders = Number(opts.minOrders);
-    if (!Number.isInteger(minOrders) || minOrders < 1) { console.error("Error: --min-orders must be an integer ≥ 1."); process.exit(1); }
     let windowDays = null;
     if (opts.window) {
       try { windowDays = parseWindowDays(opts.window); }
       catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
     }
-    cohortSpec = { min_orders: minOrders, window_days: windowDays, platform: opts.platform || "auto" };
-    cohort = { ids: [], badUuids: [], sourceMeta: { type: "order_cohort", ...cohortSpec } };
+    if (productMode) {
+      const terms = String(opts.bought).split(",").map((s) => s.trim()).filter(Boolean);
+      if (!terms.length) { console.error("Error: --bought needs at least one product name (comma-separate several)."); process.exit(1); }
+      const match = opts.match === "all" ? "all" : "any";
+      let minPurchases = 1;
+      if (opts.minPurchases !== undefined) {
+        minPurchases = Number(opts.minPurchases);
+        if (!Number.isInteger(minPurchases) || minPurchases < 1) { console.error("Error: --min-purchases must be an integer ≥ 1."); process.exit(1); }
+      }
+      cohortSpec = { product_terms: terms, match, min_purchases: minPurchases, window_days: windowDays, platform: opts.platform || "auto" };
+      cohort = { ids: [], badUuids: [], sourceMeta: { type: "product_cohort", ...cohortSpec } };
+    } else {
+      const minOrders = Number(opts.minOrders);
+      if (!Number.isInteger(minOrders) || minOrders < 1) { console.error("Error: --min-orders must be an integer ≥ 1."); process.exit(1); }
+      cohortSpec = { min_orders: minOrders, window_days: windowDays, platform: opts.platform || "auto" };
+      cohort = { ids: [], badUuids: [], sourceMeta: { type: "order_cohort", ...cohortSpec } };
+    }
   } else {
     try { cohort = await readCohort(opts, orgId); }
     catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
@@ -143,7 +161,13 @@ export async function plan(orgId, opts = {}) {
   }
   if (resp.cohort) {
     const w = resp.cohort.window_days ? `in the last ${resp.cohort.window_days} days` : "across all captured history";
-    console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+    if (resp.cohort.kind === "product") {
+      const verb = resp.cohort.min_purchases > 1 ? `bought ${resp.cohort.min_purchases}+ times` : "bought";
+      const join = resp.cohort.match === "all" ? "ALL of" : "any of";
+      console.log(`Cohort: ${verb} ${join} [${resp.cohort.product_terms.join(", ")}] ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from order line-items).`);
+    } else {
+      console.log(`Cohort: ${resp.cohort.min_orders}+ orders ${w} → ${resp.cohort.resolved_count} contact(s) (server-resolved from captured orders).`);
+    }
     cohort.sourceMeta.resolved_count = resp.cohort.resolved_count;
   }
   if (!resp.safe_count) { console.error("Nothing to tag — 0 safe contacts after exclusions (V-13)."); process.exit(1); }

package/src/commands/tag.js

@@ -0,0 +1,180 @@
+// `flowiq tag` — the Advanced Tagging surface (the Contacts → "Advanced
+// Tagging" dialog) in the terminal. Applies ONE named tag to a matched set,
+// mirroring the app's five tabs, DRY-RUN by default (add --commit to write).
+// The batch-tag slicing for controlled sends is `flowiq segments` instead.
+//
+//   flowiq tag field   <org> --field order_history --any "Protein Water,Whey" --tag whey-buyers
+//   flowiq tag cohort  <org> --type top_spenders --limit 500 --tag vip
+//   flowiq tag segment <org> --min-orders 2 --min-spent 1000 --region ZA-GP --tag gp-repeat
+//   flowiq tag attributes <org> --filter allow_broadcast_true --tag broadcastable
+//   flowiq tag messages   <org> --min-count 3 --sender user-whatsapp --tag engaged
+//   flowiq tag list    <org>
+//   flowiq tag remove  <org> <tag>[,<tag>...] --confirm
+//
+// Every match mode prints the dry-run count + a sample; nothing writes until
+// --commit AND (for large writes) a typed confirmation. Appends only — it
+// never removes or overwrites a contact's other tags.
+
+import readline from "node:readline";
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function ask(q) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(q, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+}
+
+function splitList(v) {
+  return v ? String(v).split(",").map((s) => s.trim()).filter(Boolean) : null;
+}
+
+function renderSample(sample) {
+  for (const s of (sample || []).slice(0, 10)) {
+    console.log(`    ${(s.name || "—").slice(0, 32).padEnd(32)} ${s.whatsapp_id || ""}`);
+  }
+}
+
+/** Shared: POST a match-mode payload, render dry-run or commit result. */
+async function runMatch(label, payload, opts) {
+  const commit = !!opts.commit;
+  const body = { ...payload, dry_run: !commit };
+  if (commit) {
+    if (!opts.tag || !opts.tag.trim()) { console.error("Error: --tag <name> is required with --commit."); process.exit(1); }
+    body.tag = opts.tag.trim();
+  }
+
+  let resp;
+  try { resp = await http.post("tag", body); }
+  catch (e) {
+    console.error(`${label} failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  if (!commit) {
+    let note = "";
+    if (resp.capped) note = " (⚠ capped at the RPC limit — narrow the query)";
+    else if (resp.top_n && resp.matched >= resp.top_n) note = ` (top ${resp.top_n} by rank — raise --limit for more)`;
+    console.log(`${label}: ${resp.matched} contact(s) match${note}.`);
+    renderSample(resp.sample);
+    console.log("");
+    console.log(`Add --tag <name> --commit to apply. (dry run — nothing written)`);
+    return;
+  }
+
+  console.log(`${label}: matched ${resp.matched} · newly tagged ${resp.tagged} · already had "${resp.tag}" ${resp.already_had}.`);
+  console.log("");
+  console.log(`Verify: flowiq tag list ${payload.organization_id}   ·   Undo: flowiq tag remove ${payload.organization_id} ${resp.tag} --confirm`);
+}
+
+// Pre-commit confirmation for large writes — mirror the segments gate.
+async function confirmLargeWrite(orgId, payload, opts, previewLabel) {
+  if (!opts.commit || opts.yes) return;
+  // Peek at the dry-run count first so the operator sees scale before committing.
+  let peek;
+  try { peek = await http.post("tag", { ...payload, dry_run: true }); } catch { return; }
+  if ((peek?.matched ?? 0) > 2000) {
+    console.log(`${previewLabel}: ${peek.matched} contact(s) would be tagged "${opts.tag}".`);
+    const a = await ask(`That's a large write. Type the tag name ("${opts.tag}") to proceed: `);
+    if (a !== opts.tag) { console.log("Mismatch — aborted, nothing tagged."); process.exit(0); }
+  }
+}
+
+export async function field(orgId, opts = {}) {
+  requireOrg(orgId);
+  const keywords = splitList(opts.any || opts.all);
+  if (!keywords) { console.error("Error: pass --any \"a,b\" (OR) or --all \"a,b\" (AND)."); process.exit(1); }
+  const payload = {
+    mode: "field", organization_id: orgId, field_name: opts.field || "order_history",
+    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive,
+  };
+  await confirmLargeWrite(orgId, payload, opts, "Field search");
+  await runMatch("Field search", payload, opts);
+}
+
+export async function cohort(orgId, opts = {}) {
+  requireOrg(orgId);
+  const payload = {
+    mode: "cohort", organization_id: orgId, cohort_type: opts.type || "top_spenders",
+    limit: opts.limit ? Number(opts.limit) : undefined, offset: opts.offset ? Number(opts.offset) : 0,
+    exclude_tags: splitList(opts.exclude),
+  };
+  await confirmLargeWrite(orgId, payload, opts, `Cohort ${payload.cohort_type}`);
+  await runMatch(`Cohort ${payload.cohort_type}`, payload, opts);
+}
+
+export async function segment(orgId, opts = {}) {
+  requireOrg(orgId);
+  const payload = {
+    mode: "segment", organization_id: orgId,
+    min_orders: opts.minOrders !== undefined ? Number(opts.minOrders) : null,
+    max_orders: opts.maxOrders !== undefined ? Number(opts.maxOrders) : null,
+    min_spent: opts.minSpent !== undefined ? Number(opts.minSpent) : null,
+    max_spent: opts.maxSpent !== undefined ? Number(opts.maxSpent) : null,
+    last_order_after: opts.after || null, last_order_before: opts.before || null,
+    regions: splitList(opts.region), keywords: splitList(opts.any || opts.all),
+    keyword_field: opts.field || "order_history", logic: opts.all ? "AND" : "OR",
+    case_sensitive: !!opts.caseSensitive, exclude_tags: splitList(opts.exclude),
+  };
+  await confirmLargeWrite(orgId, payload, opts, "Custom segment");
+  await runMatch("Custom segment", payload, opts);
+}
+
+export async function attributes(orgId, opts = {}) {
+  requireOrg(orgId);
+  const payload = {
+    mode: "attributes", organization_id: orgId, filter_type: opts.filter || "all_contacts",
+    include_tags: splitList(opts.include), exclude_tags: splitList(opts.exclude),
+  };
+  await confirmLargeWrite(orgId, payload, opts, `Attributes ${payload.filter_type}`);
+  await runMatch(`Attributes ${payload.filter_type}`, payload, opts);
+}
+
+export async function messages(orgId, opts = {}) {
+  requireOrg(orgId);
+  const payload = {
+    mode: "messages", organization_id: orgId, min_count: Number(opts.minCount ?? 3),
+    max_count: opts.maxCount !== undefined ? Number(opts.maxCount) : null,
+    sender_types: splitList(opts.sender) || ["user-whatsapp"],
+    excluded_messages: opts.excludeMessages ? String(opts.excludeMessages).split("|").map((s) => s.trim()).filter(Boolean) : ["View More", "VIEW MORE"],
+    date_after: opts.after || null, date_before: opts.before || null, exclude_tags: splitList(opts.exclude),
+  };
+  await confirmLargeWrite(orgId, payload, opts, "Message activity");
+  await runMatch("Message activity", payload, opts);
+}
+
+export async function list(orgId, opts = {}) {
+  requireOrg(orgId);
+  let resp;
+  try { resp = await http.post("tag", { mode: "list", organization_id: orgId }); }
+  catch (e) { console.error(`List failed: ${e.message}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.tags?.length) { console.log(`(no tags on ${resp.organization_name})`); return; }
+  const shown = opts.prefix ? resp.tags.filter((t) => String(t.tag).startsWith(opts.prefix)) : resp.tags;
+  for (const t of shown.slice(0, opts.limit ? Number(opts.limit) : 60)) {
+    console.log(`  ${String(t.tag).slice(0, 44).padEnd(44)} ${t.count}`);
+  }
+  console.log(`  ${"—".padEnd(44)}`);
+  console.log(`  ${shown.length} tag(s) on ${resp.organization_name}`);
+}
+
+export async function remove(orgId, tagArg, opts = {}) {
+  requireOrg(orgId);
+  const tags = splitList(tagArg);
+  if (!tags || !tags.length) { console.error("Error: pass one or more tag names (comma-separated)."); process.exit(1); }
+  if (!opts.confirm) {
+    console.log(`DRY RUN — would remove ${tags.length} tag(s) from all contacts: ${tags.join(", ")}. Add --confirm to remove.`);
+    return;
+  }
+  let resp;
+  try { resp = await http.post("tag", { mode: "remove", organization_id: orgId, tags }); }
+  catch (e) { console.error(`Remove failed: ${e.message}`); process.exit(1); }
+  console.log(`Removed ${tags.join(", ")} from ${resp.contacts_touched} contact(s) on ${resp.organization_name}.`);
+}

package/src/index.js

@@ -26,6 +26,7 @@ import * as knowledgeCmd from "./commands/knowledge.js";
 import * as customToolsCmd from "./commands/custom-tools.js";
 import * as broadcastCmd from "./commands/broadcast.js";
 import * as segmentsCmd from "./commands/segments.js";
+import * as tagCmd from "./commands/tag.js";
 import * as keywordsCmd from "./commands/keywords.js";
 import * as guideCmd from "./commands/guide.js";
 
@@ -409,13 +410,16 @@ export function run(argv) {
     .alias("seg")
     .description("Slice a contact cohort into fixed-size batch tags and bulk-apply them (broadcast batching)");
   segments.command("plan <organization_id>")
-    .description("Resolve a cohort (id list OR order-count criteria), apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
+    .description("Resolve a cohort (id list, order-count, or product-purchase criteria), apply broadcast-safety exclusions, slice into N-sized batch tags, write the plan (no DB write)")
     .requiredOption("--tag-prefix <name>", "campaign tag stem; batches become <prefix>-batch-NN")
     .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("--min-orders <n>", "SERVER-RESOLVED cohort: contacts with ≥ n captured orders (instead of an id file)")
-    .option("--window <span>", "with --min-orders: only count orders in this window, e.g. 60d / 8w / 3m (omit = all captured history)")
-    .option("--platform <p>", "with --min-orders: auto | shopify | woo", "auto")
+    .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")
+    .option("--min-purchases <n>", "with --bought: require ≥ n distinct orders containing the product")
+    .option("--window <span>", "with --min-orders/--bought: only count orders in this window, e.g. 60d / 8w / 3m (omit = all captured history)")
+    .option("--platform <p>", "with --min-orders/--bought: auto | shopify | woo", "auto")
     .option("--batch-size <n>", "contacts per batch tag", "75")
     .option("--segment <name>", "plan file slug (default: the tag prefix)")
     .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
@@ -436,6 +440,74 @@ export function run(argv) {
     .option("--confirm", "required alongside --commit")
     .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
 
+  // tag (the Advanced Tagging dialog in the terminal — ONE named tag on a matched set; dry-run default)
+  const tag = program.command("tag")
+    .description("Advanced Tagging: apply one named tag to a matched set of contacts (dry-run by default; --commit to write)");
+  tag.command("field <organization_id>")
+    .description("Tag contacts whose FIELD contains keyword(s). --field order_history|contact_context|contact_summary|shopify_tags|full_name|email|whatsapp_id|phone_number")
+    .option("--field <name>", "field to search", "order_history")
+    .option("--any <csv>", "match ANY of these comma-separated keywords (OR)")
+    .option("--all <csv>", "match ALL of these comma-separated keywords (AND)")
+    .option("--case-sensitive", "case-sensitive match")
+    .option("--tag <name>", "tag to apply (required with --commit)")
+    .option("--commit", "write the tag (omit = dry-run count + sample)")
+    .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")
+    .action((orgId, opts) => tagCmd.field(orgId, opts));
+  tag.command("cohort <organization_id>")
+    .description("Tag a ranked cohort (top-N). --type top_spenders|frequent_buyers|recent_buyers|high_value_low_frequency")
+    .option("--type <t>", "cohort type", "top_spenders")
+    .option("--limit <n>", "how many top contacts to tag (commit)", "1000")
+    .option("--offset <n>", "skip the first N", "0")
+    .option("--exclude <csv>", "exclude contacts already carrying any of these tags")
+    .option("--tag <name>", "tag to apply (required with --commit)")
+    .option("--commit", "write the tag (omit = dry-run count + sample)")
+    .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")
+    .action((orgId, opts) => tagCmd.cohort(orgId, opts));
+  tag.command("segment <organization_id>")
+    .description("Tag a custom segment: order-count / spend / last-order-date / region / keyword filters (reads the denormalized columns)")
+    .option("--min-orders <n>").option("--max-orders <n>")
+    .option("--min-spent <n>").option("--max-spent <n>")
+    .option("--after <date>", "last order on/after YYYY-MM-DD").option("--before <date>", "last order on/before YYYY-MM-DD")
+    .option("--region <csv>", "customer_regions contains any of these (e.g. ZA-GP,ZA-WC)")
+    .option("--any <csv>", "keyword match ANY (OR)").option("--all <csv>", "keyword match ALL (AND)")
+    .option("--field <name>", "keyword search field", "order_history")
+    .option("--case-sensitive", "case-sensitive keyword match")
+    .option("--exclude <csv>", "exclude contacts already carrying any of these tags")
+    .option("--tag <name>", "tag to apply (required with --commit)")
+    .option("--commit", "write the tag (omit = dry-run count + sample)")
+    .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")
+    .action((orgId, opts) => tagCmd.segment(orgId, opts));
+  tag.command("attributes <organization_id>")
+    .description("Tag by broadcast permission. --filter all_contacts|allow_broadcast_true|allow_broadcast_false|no_broadcast_permission")
+    .option("--filter <f>", "attribute filter", "all_contacts")
+    .option("--include <csv>", "only contacts carrying any of these tags")
+    .option("--exclude <csv>", "exclude contacts carrying any of these tags")
+    .option("--tag <name>", "tag to apply (required with --commit)")
+    .option("--commit", "write the tag (omit = dry-run count + sample)")
+    .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")
+    .action((orgId, opts) => tagCmd.attributes(orgId, opts));
+  tag.command("messages <organization_id>")
+    .description("Tag by message activity: contacts with ≥ N messages of the given sender type(s) in an optional date range")
+    .option("--min-count <n>", "minimum message count", "3").option("--max-count <n>")
+    .option("--sender <csv>", "sender types (e.g. user-whatsapp,user-web)", "user-whatsapp")
+    .option("--exclude-messages <pipe>", "pipe-separated messages to ignore (default: View More|VIEW MORE)")
+    .option("--after <date>", "messages on/after YYYY-MM-DD").option("--before <date>", "messages on/before YYYY-MM-DD")
+    .option("--exclude <csv>", "exclude contacts already carrying any of these tags")
+    .option("--tag <name>", "tag to apply (required with --commit)")
+    .option("--commit", "write the tag (omit = dry-run count + sample)")
+    .option("--yes", "skip the type-the-tag confirm on large (>2000) writes")
+    .action((orgId, opts) => tagCmd.messages(orgId, opts));
+  tag.command("list <organization_id>")
+    .description("List the org's tags with contact counts (read-only)")
+    .option("--prefix <substr>", "only tags starting with this")
+    .option("--limit <n>", "cap rows printed", "60")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => tagCmd.list(orgId, opts));
+  tag.command("remove <organization_id> <tags>")
+    .description("Remove tag(s) (comma-separated) from ALL contacts in the org. Destructive — needs --confirm")
+    .option("--confirm", "actually remove (omit = dry-run)")
+    .action((orgId, tags, opts) => tagCmd.remove(orgId, tags, opts));
+
   // keywords (org auto-reply engine: keywords + keyword_actions; id-keyed diff push)
   const keywords = program.command("keywords")
     .alias("kw")