@flowapt/flowiq-cli 0.4.1 → 0.4.2

package/README.md

@@ -405,6 +405,9 @@ flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP --tag
 
 # Attributes — broadcast permission (all_contacts / allow_broadcast_true|false / no_broadcast_permission)
 flowiq tag attributes <org_id> --filter allow_broadcast_true --tag broadcastable --commit
+# Big org (cohort > ~20k)? Chunk it: repeat this until it reports "matched 0" —
+# each run tags the next 10k untagged contacts (see the bullet below on the 50k cap / DB timeout)
+flowiq tag attributes <org_id> --filter allow_broadcast_true --limit 10000 --exclude broadcastable --tag broadcastable --commit --yes
 
 # 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
@@ -422,6 +425,12 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
 - **`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.
+- **Big orgs: chunk `attributes` commits with `--limit` + `--exclude <your-tag>`**
+  (flags added 3 Aug 2026, in-repo pending publish). The tagging RPC hard-caps at 50,000
+  per call AND a single large commit updates row-by-row, so a ~50k commit dies
+  on the DB statement timeout (full rollback, nothing written). `--limit 10000
+  --exclude <the-tag-you're-adding>` makes each run pick the next 10k untagged
+  matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
 ### Keywords — `flowiq keywords pull|push|list` (alias `kw`)

package/TEAM-GUIDE.md

@@ -179,6 +179,18 @@ real order line-items (accurate + windowable) rather than the order-history text
 And a commit over 2000 contacts asks you to type the tag name to confirm
 (add `--yes` to skip). Everything is appends-only and reversible with `tag remove`.
 
+**Tagging a very large audience (20k+, e.g. "everyone opted in") with `attributes`?**
+One giant commit will fail on a database timeout (nothing writes). Chunk it instead:
+
+```bash
+# repeat this exact line until it prints "matched 0" — each run tags the NEXT 10k
+flowiq tag attributes <org_id> --filter allow_broadcast_true \
+  --limit 10000 --exclude my-campaign-tag --tag my-campaign-tag --commit --yes
+```
+
+`--exclude` names the same tag you're adding, so every run skips the people who
+already have it. Safe to re-run as many times as you like.
+
 ## Keys, rotation, logging out
 
 - **`flowiq auth refresh`** — rotates this device's key in place (a fresh key

package/package.json

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

@@ -132,6 +132,7 @@ export async function attributes(orgId, opts = {}) {
   const payload = {
     mode: "attributes", organization_id: orgId, filter_type: opts.filter || "all_contacts",
     include_tags: splitList(opts.include), exclude_tags: splitList(opts.exclude),
+    limit: opts.limit ? Number(opts.limit) : undefined, offset: opts.offset ? Number(opts.offset) : 0,
   };
   await confirmLargeWrite(orgId, payload, opts, `Attributes ${payload.filter_type}`);
   await runMatch(`Attributes ${payload.filter_type}`, payload, opts);

package/src/index.js

@@ -550,6 +550,8 @@ export function run(argv) {
     .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("--limit <n>", "max contacts per run (default 50000 — the RPC cap; a 50k commit can hit the DB statement timeout, so chunk big orgs: --limit 10000 --exclude <tag>, re-run until 0 match)")
+    .option("--offset <n>", "skip the first N", "0")
     .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")