@flowapt/flowiq-cli 0.2.1 → 0.2.4

package/README.md

@@ -155,6 +155,7 @@ flowiq ct list
 ```
 
 - **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
+- **Destructive pushes are blocked by default**: a push that removes a tool, disables one, or sends an empty `tools[]` (wiping everything) writes nothing and shows you exactly what it would strip — re-run with `--confirm` if intentional. Additive/no-op pushes are unaffected.
 - Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Bad payloads are rejected before anything writes.
 - **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime — known: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
@@ -244,6 +245,33 @@ flowiq seg untag <org_id> july-promo --commit --confirm   # ROLLBACK (its own ta
 - Point-in-time warning: the plan tags snapshot ids; re-derive the cohort SQL
   if freshness matters (someone who ordered since won't auto-drop).
 
+### Keywords — `flowiq keywords pull|push|list` (alias `kw`)
+
+Round-trips an org's **keyword auto-reply engine** — the `keywords` +
+`keyword_actions` rows that fire instant replies / contact updates when a
+customer message matches a trigger word. This is the **safe editor** for the
+attribute-write actions (competition entries) that the dashboard editor
+corrupts on save.
+
+```bash
+flowiq kw pull <org_id>                 # → ./.flowiq/keywords/<slug>.json (all keywords + actions)
+flowiq kw push <slug> --dry-run          # plan: created/updated/deleted at both levels, no write
+flowiq kw push <slug>                    # id-keyed upsert (never touches keywords absent from the file)
+flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from the file (dry-run first!)
+```
+
+- **Identity = the `id`s.** Keep an id to update that row; drop the id to
+  create a new one; remove an *action* from a kept keyword to delete it.
+  A file id that doesn't exist for the org aborts (stale file → re-pull).
+- **Pull immediately before editing** — clients edit auto-reply copy live.
+- `text` is stored **verbatim** (byte-identical — required when the reply
+  must match a prompt quote exactly). `position` must be ≥ 1 (0 silently
+  collapses to 1 at runtime — rejected).
+- `field:"attributes"` actions are warned (full jsonb replace; constant
+  values only) but applied — this CLI is their only safe editing surface.
+- Scheduled keywords: the keyword-scheduler cron reconciles `active` from
+  `start_date`/`end_date` within ~30 min of your push.
+
 ### Messages — `flowiq messages pull <contact_id>` (alias `m`)
 
 Read-only pull of a contact's `helpdesk_messages` history. Anchors on the
@@ -388,15 +416,28 @@ Media headers: pass `media_header.file_url` (a public URL) — the edge function
 uploads it to Meta server-side. Approval is async; re-`pull` for the
 authoritative Meta status.
 
-### Org info — `flowiq org info <organization_id>`
+### Org — `flowiq org create` / `flowiq org info <organization_id>`
 
-Read-only platform detect + active-agent lookup for an org (raw store/Meta
+Create a brand-new organization, or look one up (read-only; raw store/Meta
 credentials are stripped server-side).
 
 ```bash
+flowiq org create --name "New Client" [--slug new-client] [--owner client@email.com] [--provider wati]
+# → org row + admin membership. Owner defaults to YOU; --owner requires the
+#   person to already have an account (otherwise invite them later in the app).
+#   Provider defaults to meta. Prints the new org id + the next-step commands.
+
 flowiq org info <organization_id>       # platform, storefront url, active agent
 ```
 
+Full new-client bootstrap from the terminal:
+```bash
+flowiq org create --name "New Client"
+flowiq agent create <new_org_id> --name "Zara" --make-active
+flowiq agent config <new_org_id> --model gpt-5.4-mini --use-settings-prompt
+flowiq prompts pull <new_org_id>   # edit → push
+```
+
 ### Agents — `flowiq agent list|create <org>`
 
 List an org's agents (to discover ids) and create a new one.

package/TEAM-GUIDE.md

@@ -67,6 +67,7 @@ flowiq auth whoami
 | Edit the text knowledge sources (get_more_answers playbooks) | `flowiq kn pull <org_id>` → edit `sources[]` → `flowiq kn push <slug>` |
 | Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
 | Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
+| Edit keyword auto-replies (incl. competition entry keywords) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug>` |
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
@@ -78,6 +79,7 @@ flowiq auth whoami
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
 | Manage outbound messaging webhooks | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
+| Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |
 | See a client's pending change requests | `flowiq au pull <org_id>` |
 | Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
 | Check an org's platform + active agent | `flowiq org info <org_id>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "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/custom-tools.js

@@ -129,6 +129,7 @@ export async function push(identifier, opts = {}) {
       agent_id: data.agent_id, // push back to the agent this file was pulled from
       tools: data.tools,
       dry_run: !!opts.dryRun,
+      confirm: !!opts.confirm,
     });
   } catch (e) {
     console.error(`Push failed: ${e.message}`);
@@ -142,6 +143,16 @@ export async function push(identifier, opts = {}) {
   console.log(`  tools:     ${resp.tool_count}`);
   printDiff(resp.diff);
   printWarnings(resp.warnings);
+  if (resp.requires_confirm) {
+    const d = resp.destructive || {};
+    console.log("");
+    console.log("  ⛔ DESTRUCTIVE PUSH — nothing was written:");
+    if (d.wipe_all) console.log("     this file would WIPE EVERY custom tool off the agent");
+    if (d.removed?.length) console.log(`     removes: ${d.removed.join(", ")}`);
+    if (d.disabled?.length) console.log(`     disables: ${d.disabled.join(", ")}`);
+    console.log("  Re-run with --confirm if this is intentional.");
+    process.exit(1);
+  }
   if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
 }
 

package/src/commands/keywords.js

@@ -0,0 +1,135 @@
+// `flowiq keywords pull <org_id>` / `push <slug> [--prune] [--dry-run]` / `list`.
+// Round-trips an org's keyword auto-replies (keywords + keyword_actions rows)
+// via /cli/keywords — the SAFE editing path for the attribute-write actions
+// the dashboard editor corrupts.
+//
+// Push is an ID-KEYED diff upsert: keep an `id` to update, drop the `id` to
+// create, remove an ACTION from a kept keyword to delete it. A DB keyword
+// absent from the file is left alone unless --prune. ALWAYS pull right before
+// editing (clients edit auto-reply copy live) and --dry-run before --prune.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const KW_DIR = path.resolve(process.cwd(), ".flowiq", "keywords");
+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 slugify(name, fallback) {
+  const s = String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function resolvePushPath(identifier) {
+  const candidates = [];
+  if (path.isAbsolute(identifier)) candidates.push(identifier);
+  else if (identifier.includes("/") || identifier.includes("\\")) candidates.push(path.resolve(identifier));
+  else {
+    const base = identifier.endsWith(".json") ? identifier : `${identifier}.json`;
+    candidates.push(path.join(KW_DIR, base));
+    candidates.push(path.resolve(base));
+  }
+  for (const c of candidates) if (await fileExists(c)) return c;
+  throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
+}
+
+export async function pull(orgId) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  let resp;
+  try { resp = await http.get("keywords", { organization_id: orgId }); }
+  catch (e) {
+    console.error(`Pull failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  await fs.mkdir(KW_DIR, { recursive: true });
+  const slug = slugify(resp.organization_name, resp.organization_id);
+  const filePath = path.join(KW_DIR, `${slug}.json`);
+  const overwriting = await fileExists(filePath);
+  await fs.writeFile(filePath, JSON.stringify(resp, null, 2) + "\n", "utf8");
+
+  console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  keywords:  ${resp.keyword_count}`);
+  for (const k of resp.keywords || []) {
+    const acts = (k.keyword_actions || []).length;
+    console.log(`    ${String(k.type).padEnd(28)} [${(k.keywords || []).join(", ")}] · ${acts} action(s)${k.active === false ? " · INACTIVE" : ""}${k.end_date ? ` · ends ${k.end_date.slice(0, 10)}` : ""}`);
+  }
+  if (resp.has_attribute_actions) {
+    console.log("");
+    console.log("  ⚠ this org has attribute-write keyword action(s) — the dashboard editor");
+    console.log("    CANNOT render field:\"attributes\" and corrupts it on save. Edit those");
+    console.log("    keywords via this CLI only.");
+  }
+}
+
+export async function push(identifier, opts = {}) {
+  let filePath;
+  try { filePath = await resolvePushPath(identifier); }
+  catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+  const raw = await fs.readFile(filePath, "utf8");
+  let data;
+  try { data = JSON.parse(raw); }
+  catch (e) { console.error(`Invalid JSON in ${filePath}: ${e.message}`); process.exit(1); }
+  if (!data.organization_id || !UUID_RE.test(data.organization_id)) {
+    console.error(`${filePath}: organization_id missing or invalid`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data.keywords)) {
+    console.error(`${filePath}: keywords must be an array`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("keywords", {
+      organization_id: data.organization_id,
+      keywords: data.keywords,
+      prune: !!opts.prune,
+      dry_run: !!opts.dryRun,
+    });
+  } catch (e) {
+    console.error(`Push failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  const p = resp.plan;
+  console.log(`${resp.dry_run ? "DRY RUN (nothing written) —" : "Pushed"} ${filePath}`);
+  console.log(`  org:       ${resp.organization_name} (${data.organization_id})`);
+  console.log(`  keywords:  +${p.keywords.create} created · ~${p.keywords.update} updated · ${p.keywords.unchanged} unchanged · -${p.keywords.delete} deleted · ${p.keywords.orphan_kept} orphan(s) kept`);
+  console.log(`  actions:   +${p.actions.create} created · ~${p.actions.update} updated · ${p.actions.unchanged} unchanged · -${p.actions.delete} deleted`);
+  for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
+  if (resp.dry_run) console.log("  re-run without --dry-run to apply.");
+  else if (resp.prune && p.keywords.delete) console.log(`  pruned ${p.keywords.delete} keyword(s) — re-pull to confirm.`);
+  if (!resp.dry_run && p.keywords.orphan_kept) {
+    console.log(`  note: ${p.keywords.orphan_kept} DB keyword(s) not in the file were left untouched (--prune to delete).`);
+  }
+}
+
+export async function list() {
+  let files;
+  try { files = (await fs.readdir(KW_DIR)).filter((f) => f.endsWith(".json")); }
+  catch { console.log("(no local keyword snapshots; run `keywords pull <org_id>`)"); return; }
+  if (!files.length) { console.log("(no local keyword snapshots)"); return; }
+  files.sort();
+  for (const f of files) {
+    try {
+      const d = JSON.parse(await fs.readFile(path.join(KW_DIR, f), "utf8"));
+      console.log(f);
+      console.log(`  org:       ${d.organization_name ?? "?"} (${d.organization_id ?? "?"})`);
+      console.log(`  keywords:  ${d.keyword_count ?? (Array.isArray(d.keywords) ? d.keywords.length : "?")}`);
+      console.log(`  pulled:    ${d.pulled_at ?? "?"}`);
+    } catch (e) {
+      console.log(`${f}  [invalid JSON: ${e.message}]`);
+    }
+  }
+}

package/src/commands/org.js

@@ -31,3 +31,39 @@ export async function info(orgId, opts = {}) {
   console.log(`  provider:      ${resp.provider || "(unset → meta)"}`);
   console.log(`  active agent:  ${resp.active_whatsapp_agent || "(NONE — set one before building a prompt)"}`);
 }
+
+// `flowiq org create --name "…" [--slug …] [--owner email] [--provider meta|wati]`
+// Creates a NEW organization (org row + admin membership), mirroring the app's
+// Create Organization dialog. Owner defaults to YOU (the staff key's user) —
+// the client gets invited later via the app's member invite flow.
+export async function create(opts = {}) {
+  if (!opts.name || !opts.name.trim()) {
+    console.error("Error: --name is required.");
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("org", {
+      action: "create",
+      name: opts.name.trim(),
+      slug: opts.slug,
+      owner_email: opts.owner,
+      provider: opts.provider,
+    });
+  } catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Created "${resp.name}"`);
+  console.log(`  id:        ${resp.id}`);
+  console.log(`  slug:      ${resp.slug}`);
+  console.log(`  owner:     ${resp.owner_email ?? resp.owner_id}${resp.member_added ? " (admin member)" : "  ⚠ membership insert failed — add via the app"}`);
+  console.log(`  provider:  ${resp.provider}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  flowiq agent create ${resp.id} --name "<AgentName>" --make-active`);
+  console.log(`  flowiq agent config ${resp.id} --model gpt-5.4-mini --use-settings-prompt`);
+  console.log(`  flowiq prompts pull ${resp.id}   # then edit + push`);
+}

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 keywordsCmd from "./commands/keywords.js";
 
 // Read version from package.json so it stays in sync with the published npm
 // version automatically (single source of truth — bumping package.json on each
@@ -190,7 +191,14 @@ export function run(argv) {
     .action((orgId, opts) => templatesCmd.status(orgId, opts));
 
   // org (read-only org summary for the prompt-builder skill, creds stripped)
-  const org = program.command("org").description("Read-only org info (platform detect + active agent)");
+  const org = program.command("org").description("Org info (read) + create a new organization");
+  org.command("create")
+    .description("Create a NEW organization (org row + admin membership; owner defaults to you)")
+    .requiredOption("--name <name>", "organization name")
+    .option("--slug <slug>", "URL slug (default: name lowercased, spaces→dashes; must be unique)")
+    .option("--owner <email>", "owner's auth email (must already have an account; default: you)")
+    .option("--provider <p>", "meta (default) | wati")
+    .action((opts) => orgCmd.create(opts));
   org.command("info <organization_id>")
     .description("Show the org's platform, storefront url + active agent (raw creds stripped)")
     .option("--json", "print the raw JSON payload")
@@ -330,8 +338,9 @@ export function run(argv) {
     .option("--agent <id>", "target a specific agent instead of the org's active one")
     .action((orgId, opts) => customToolsCmd.pull(orgId, opts));
   customTools.command("push <slug-or-path>")
-    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side)")
+    .description("FULL-REPLACE the agent's custom tools with the local JSON's tools[] (validated server-side). Destructive pushes (remove/disable/wipe) are BLOCKED unless --confirm.")
     .option("--dry-run", "validate + print the per-tool diff WITHOUT writing")
+    .option("--confirm", "required when the push removes or disables tools, or sends an empty tools[]")
     .action((id, opts) => customToolsCmd.push(id, opts));
   customTools.command("enable <organization_id> <tool_name>")
     .description("Enable one custom tool by name (no round-trip)")
@@ -423,5 +432,21 @@ export function run(argv) {
     .option("--confirm", "required alongside --commit")
     .action((orgId, id, opts) => segmentsCmd.untag(orgId, id, opts));
 
+  // keywords (org auto-reply engine: keywords + keyword_actions; id-keyed diff push)
+  const keywords = program.command("keywords")
+    .alias("kw")
+    .description("Round-trip an org's keyword auto-replies + actions (the safe editor for attribute-write actions)");
+  keywords.command("pull <organization_id>")
+    .description("Fetch every keyword + its actions into a local JSON file (ALWAYS pull right before editing)")
+    .action((orgId) => keywordsCmd.pull(orgId));
+  keywords.command("push <slug-or-path>")
+    .description("Apply the local JSON: id-keyed UPSERT (keep ids to update, drop ids to create). --prune also DELETES keywords absent from the file.")
+    .option("--prune", "also delete DB keywords whose id is not in the file (destructive; cascade-deletes their actions)")
+    .option("--dry-run", "compute + print the plan without writing (ALWAYS before --prune)")
+    .action((id, opts) => keywordsCmd.push(id, opts));
+  keywords.command("list")
+    .description("List local keyword snapshots")
+    .action(() => keywordsCmd.list());
+
   program.parseAsync(argv);
 }