@flowapt/flowiq-cli 0.1.7 → 0.1.8

package/README.md

@@ -252,6 +252,37 @@ credentials are stripped server-side).
 flowiq org info <organization_id>       # platform, storefront url, active agent
 ```
 
+### Agents — `flowiq agent list|create <org>`
+
+List an org's agents (to discover ids) and create a new one.
+
+```bash
+flowiq agent list <organization_id>        # ★ marks the active agent; shows each id
+flowiq agent create <organization_id> --name "Zara" \
+  --system-prompt-file ./zara-prompt.txt --make-active
+```
+
+`create` inserts a new agent (`created_by` = your staff-key identity), optionally
+seeds its prompt into a single "Main" section, and — with `--make-active` — sets
+it as the org's `active_whatsapp_agent`. New agents start on the app default
+model; set the house model afterwards with `agent config … --model gpt-5.4-mini
+--use-settings-prompt`.
+
+### Targeting a specific agent — `--agent <id>`
+
+By default `prompts`, `questionnaires`, `fine-tuning`, and `agent config` all act
+on the org's **active** agent. To target a **different** agent, pass `--agent <id>`
+(get ids from `agent list`):
+
+```bash
+flowiq prompts pull <org> --agent <agent_id>      # pull a NON-active agent's prompt
+flowiq prompts push <slug>                          # pushes back to that same agent (id is in the file)
+flowiq agent config <org> --agent <agent_id> --model gpt-5.4-mini
+```
+
+`pull` records the agent id in the JSON, so `push` always writes back to the exact
+agent you pulled from (never "whatever is active now").
+
 ### Agent config — `flowiq agent config <organization_id> [flags]`
 
 Set an allowlisted set of the active agent's config fields (the prompt-builder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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/agent-config.js

@@ -37,6 +37,7 @@ export async function config(orgId, opts = {}) {
   }
 
   const body = { organization_id: orgId };
+  if (opts.agent !== undefined) body.agent_id = opts.agent;
   const settings = {};
   if (opts.useSettingsPrompt !== undefined) settings.use_settings_prompt = parseBool(opts.useSettingsPrompt, "--use-settings-prompt");
   if (opts.model !== undefined) settings.model = opts.model;
@@ -65,12 +66,12 @@ export async function config(orgId, opts = {}) {
   if (!hasWrite) {
     let resp;
     try {
-      resp = await http.get("agent-config", { organization_id: orgId });
+      resp = await http.get("agent-config", { organization_id: orgId, agent_id: opts.agent });
     } catch (e) {
       console.error(`Lookup failed: ${e.message}`);
       process.exit(1);
     }
-    console.log(`${resp.organization_name} → agent ${resp.agent_id}`);
+    console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
     printSnapshot("current", resp.current);
     console.log("\n(pass --use-settings-prompt / --model / --rename / --tool / --discount to change)");
     return;
@@ -85,7 +86,7 @@ export async function config(orgId, opts = {}) {
     process.exit(1);
   }
 
-  console.log(`Updated agent ${resp.agent_id} (${resp.organization_name})`);
+  console.log(`Updated agent ${resp.agent_id} (${resp.organization_name})${resp.is_active === false ? " [NON-active]" : ""}`);
   console.log(`  changed: ${resp.changed.join(", ") || "(nothing)"}`);
   for (const k of resp.changed) {
     const b = resp.before?.[k];

package/src/commands/agents.js

@@ -0,0 +1,76 @@
+// `flowiq agent list <org>` / `flowiq agent create <org> --name … [flags]`.
+// List an org's agents (to discover ids for --agent targeting) and create a
+// new agent via /cli/agents.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+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;
+
+export async function list(orgId, opts = {}) {
+  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("agents", { 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; }
+
+  const agents = resp.agents || [];
+  console.log(`${resp.organization_name} (${resp.organization_id}) — ${agents.length} agent${agents.length === 1 ? "" : "s"}:`);
+  if (!agents.length) { console.log("  (none — create one with `agent create`)"); return; }
+  for (const a of agents) {
+    const created = a.created_at ? new Date(a.created_at).toISOString().slice(0, 10) : "?";
+    console.log(`  ${a.is_active ? "★" : " "} ${a.id}  ${created}  ${a.name}`);
+  }
+  console.log("\n★ = active agent. Pass any id as --agent <id> to prompts/questionnaires/fine-tuning/agent config.");
+}
+
+export async function create(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID.`);
+    process.exit(1);
+  }
+  if (!opts.name || !String(opts.name).trim()) {
+    console.error("Error: --name <name> is required.");
+    process.exit(1);
+  }
+
+  let systemPrompt;
+  if (opts.systemPromptFile) {
+    let fp = opts.systemPromptFile;
+    if (!path.isAbsolute(fp)) fp = path.resolve(fp);
+    try { systemPrompt = await fs.readFile(fp, "utf8"); }
+    catch (e) { console.error(`Cannot read --system-prompt-file ${fp}: ${e.message}`); process.exit(1); }
+  } else if (opts.systemPrompt !== undefined) {
+    systemPrompt = opts.systemPrompt;
+  }
+
+  let resp;
+  try {
+    resp = await http.post("agents", {
+      organization_id: orgId,
+      name: opts.name,
+      system_prompt: systemPrompt,
+      make_active: !!opts.makeActive,
+    });
+  } catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    if (e.body?.error) console.error(`  ${e.body.error}`);
+    process.exit(1);
+  }
+
+  console.log(`Created agent "${resp.agent_name}" (${resp.agent_id})`);
+  console.log(`  org:           ${resp.organization_name} (${resp.organization_id})`);
+  console.log(`  active:        ${resp.is_active ? "yes (set as the org's active agent)" : "no"}`);
+  console.log(`  seeded prompt: ${resp.seeded_prompt ? "yes (single \"Main\" section)" : "no (default settings)"}`);
+  if (resp.warning) console.log(`  ⚠ ${resp.warning}`);
+  console.log("\nNext: `agent config " + orgId + " --agent " + resp.agent_id + " --use-settings-prompt --model gpt-5.4-mini`");
+  console.log("      then `prompts pull " + orgId + " --agent " + resp.agent_id + "` to author the full prompt.");
+}

package/src/commands/fine-tuning.js

@@ -53,14 +53,14 @@ function countEntries(entries) {
   return { total: entries.length, pending, resolved, byCategory };
 }
 
-export async function pull(orgId) {
+export async function pull(orgId, opts = {}) {
   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("fine-tuning", { organization_id: orgId });
+    resp = await http.get("fine-tuning", { organization_id: orgId, agent_id: opts.agent });
   } catch (e) {
     console.error(`Pull failed: ${e.message}`);
     process.exit(1);
@@ -75,7 +75,7 @@ export async function pull(orgId) {
   const stats = countEntries(resp.fine_tuning_entries);
   console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
   console.log(`  org:           ${resp.organization_name} (${resp.organization_id})`);
-  console.log(`  agent:         ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`  agent:         ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
   console.log(`  instructions:  ${resp.fine_tuning.length} chars`);
   console.log(`  entries:       ${stats.total} (${stats.pending} pending, ${stats.resolved} resolved)`);
   if (stats.total > 0) {
@@ -118,6 +118,7 @@ export async function push(identifier) {
       organization_id: data.organization_id,
       fine_tuning: data.fine_tuning,
       fine_tuning_entries: data.fine_tuning_entries ?? [],
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
     });
   } catch (e) {
     console.error(`Push failed: ${e.message}`);

package/src/commands/prompts.js

@@ -40,14 +40,14 @@ async function resolvePushPath(identifier) {
   throw new Error(`File not found. Tried:\n  ${candidates.join("\n  ")}`);
 }
 
-export async function pull(orgId) {
+export async function pull(orgId, opts = {}) {
   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("prompts", { organization_id: orgId });
+    resp = await http.get("prompts", { organization_id: orgId, agent_id: opts.agent });
   } catch (e) {
     console.error(`Pull failed: ${e.message}`);
     process.exit(1);
@@ -62,7 +62,7 @@ export async function pull(orgId) {
   const totalChars = resp.prompt_sections.reduce((a, s) => a + (s.content?.length || 0), 0);
   console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
   console.log(`  org:       ${resp.organization_name} (${resp.organization_id})`);
-  console.log(`  agent:     ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`  agent:     ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
   console.log(`  sections:  ${resp.prompt_sections.length}`);
   console.log(`  content:   ${totalChars.toLocaleString()} chars`);
   if (resp.bootstrapped) {
@@ -105,6 +105,7 @@ export async function push(identifier) {
     resp = await http.post("prompts", {
       organization_id: data.organization_id,
       prompt_sections: data.prompt_sections,
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
     });
   } catch (e) {
     console.error(`Push failed: ${e.message}`);

package/src/commands/questionnaires.js

@@ -53,14 +53,14 @@ function countQuestions(sections) {
   return { total, answered };
 }
 
-export async function pull(orgId) {
+export async function pull(orgId, opts = {}) {
   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("questionnaires", { organization_id: orgId });
+    resp = await http.get("questionnaires", { organization_id: orgId, agent_id: opts.agent });
   } catch (e) {
     console.error(`Pull failed: ${e.message}`);
     process.exit(1);
@@ -75,7 +75,7 @@ export async function pull(orgId) {
   const { total, answered } = countQuestions(resp.questionnaire?.sections);
   console.log(`${overwriting ? "Overwrote" : "Wrote"} ${filePath}`);
   console.log(`  org:        ${resp.organization_name} (${resp.organization_id})`);
-  console.log(`  agent:      ${resp.agent_name} (${resp.agent_id})`);
+  console.log(`  agent:      ${resp.agent_name} (${resp.agent_id})${resp.is_active === false ? " [NON-active]" : ""}`);
   console.log(`  sections:   ${resp.questionnaire?.sections?.length ?? 0}`);
   console.log(`  questions:  ${answered}/${total} answered`);
   if (resp.default_used) {
@@ -114,6 +114,7 @@ export async function push(identifier) {
     resp = await http.post("questionnaires", {
       organization_id: data.organization_id,
       questionnaire: data.questionnaire,
+      agent_id: data.agent_id, // push back to the agent this file was pulled from
     });
   } catch (e) {
     console.error(`Push failed: ${e.message}`);

package/src/index.js

@@ -18,6 +18,7 @@ import * as pinboardCmd from "./commands/pinboard.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
+import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
@@ -48,10 +49,11 @@ export function run(argv) {
   // prompts
   const prompts = program.command("prompts").description("Round-trip an org's active WhatsApp agent system prompt");
   prompts.command("pull <organization_id>")
-    .description("Fetch the active agent's prompt_sections into a local JSON file")
-    .action((orgId) => promptsCmd.pull(orgId));
+    .description("Fetch an agent's prompt_sections into a local JSON file (default: active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => promptsCmd.pull(orgId, opts));
   prompts.command("push <slug-or-path>")
-    .description("Apply a local JSON file's prompt_sections to the agent (regenerates system_prompt server-side)")
+    .description("Apply a local JSON file's prompt_sections back to the agent it was pulled from (regenerates system_prompt server-side)")
     .action((id) => promptsCmd.push(id));
 
   // questionnaires
@@ -59,10 +61,11 @@ export function run(argv) {
     .alias("q")
     .description("Round-trip an org's active WhatsApp agent's questionnaire answers (agents.questionnaire JSONB)");
   qs.command("pull <organization_id>")
-    .description("Fetch the active agent's questionnaire into a local JSON file (seeds from DEFAULT_QUESTIONNAIRE if the DB column is empty)")
-    .action((orgId) => questionnairesCmd.pull(orgId));
+    .description("Fetch an agent's questionnaire into a local JSON file (default: active agent; seeds DEFAULT_QUESTIONNAIRE if empty)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => questionnairesCmd.pull(orgId, opts));
   qs.command("push <slug-or-path>")
-    .description("Apply a local JSON file's questionnaire to the agent")
+    .description("Apply a local JSON file's questionnaire back to the agent it was pulled from")
     .action((id) => questionnairesCmd.push(id));
 
   // messages (read-only: pull a contact's helpdesk_messages history)
@@ -79,10 +82,11 @@ export function run(argv) {
     .alias("ft")
     .description("Round-trip the active agent's fine-tuning instructions + Q&A entries");
   ft.command("pull <organization_id>")
-    .description("Fetch agents.fine_tuning + agents.fine_tuning_entries into a local JSON file")
-    .action((orgId) => fineTuningCmd.pull(orgId));
+    .description("Fetch an agent's fine_tuning + fine_tuning_entries into a local JSON file (default: active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
+    .action((orgId, opts) => fineTuningCmd.pull(orgId, opts));
   ft.command("push <slug-or-path>")
-    .description("Apply a local JSON file's fine_tuning + fine_tuning_entries to the agent")
+    .description("Apply a local JSON file's fine_tuning + fine_tuning_entries back to the agent it was pulled from")
     .action((id) => fineTuningCmd.push(id));
 
   // messaging-webhooks (outbound notifications via meta_webhooks table)
@@ -184,10 +188,22 @@ export function run(argv) {
     .option("--json", "print the raw JSON payload")
     .action((orgId, opts) => orgCmd.info(orgId, opts));
 
-  // agent (agent-level config writes: the prompt-builder skill's Step 5)
-  const agent = program.command("agent").description("Configure the org's active agent");
+  // agent (list / create / config — config defaults to the active agent, or --agent <id>)
+  const agent = program.command("agent").description("List, create, and configure an org's agents");
+  agent.command("list <organization_id>")
+    .description("List the org's agents (★ = active); use an id as --agent <id> elsewhere")
+    .option("--json", "print the raw JSON payload")
+    .action((orgId, opts) => agentsCmd.list(orgId, opts));
+  agent.command("create <organization_id>")
+    .description("Create a new agent (optionally seed its prompt + set it active)")
+    .requiredOption("--name <name>", "agent name")
+    .option("--system-prompt <text>", "seed the prompt (single \"Main\" section)")
+    .option("--system-prompt-file <path>", "seed the prompt from a file")
+    .option("--make-active", "set the new agent as the org's active_whatsapp_agent")
+    .action((orgId, opts) => agentsCmd.create(orgId, opts));
   agent.command("config <organization_id>")
-    .description("Set allowlisted agent config (no flags = show current)")
+    .description("Set allowlisted agent config (no write flags = show current; defaults to the active agent)")
+    .option("--agent <id>", "target a specific agent instead of the org's active one")
     .option("--use-settings-prompt [bool]", "settings.use_settings_prompt (true if bare)")
     .option("--model <model>", "settings.model (e.g. gpt-5.4-mini)")
     .option("--rename <name>", "rename the agent")