@intercom/cli 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,105 +1,22 @@
 #!/usr/bin/env node
+import {
+  AuthError,
+  CLIError,
+  NotFoundError,
+  PermissionError,
+  RateLimitError,
+  TimeoutError,
+  applyJq,
+  detectAuthType,
+  formatJson
+} from "./chunk-QEXGKXTU.js";
 
 // src/index.ts
 import { Command } from "commander";
 
-// src/types.ts
-var CLIError = class extends Error {
-  constructor(message, exitCode = 1, error) {
-    super(message);
-    this.exitCode = exitCode;
-    this.error = error;
-    this.name = "CLIError";
-  }
-};
-var AuthError = class extends CLIError {
-  constructor(message) {
-    super(message, 2);
-  }
-};
-var RateLimitError = class extends CLIError {
-  constructor(message, retryAfter) {
-    super(message, 3);
-    this.retryAfter = retryAfter;
-  }
-};
-var NotFoundError = class extends CLIError {
-  constructor(message) {
-    super(message, 4);
-  }
-};
-var PermissionError = class extends CLIError {
-  constructor(message) {
-    super(message, 5);
-  }
-};
-var TimeoutError = class extends CLIError {
-  constructor(message) {
-    super(message, 6);
-  }
-};
-function detectAuthType(token) {
-  try {
-    const decoded = Buffer.from(token, "base64").toString("utf-8");
-    if (decoded.startsWith("tok:")) {
-      return "oauth";
-    }
-  } catch {
-  }
-  return "api_key";
-}
-
-// src/output/json.ts
-function formatJson(data) {
-  return JSON.stringify(data, null, 2);
-}
-function applyJq(data, expr) {
-  if (expr === ".") return data;
-  if (!expr.startsWith(".")) {
-    throw new CLIError(
-      `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
-    );
-  }
-  if (/[|(){},;]/.test(expr)) {
-    throw new CLIError(
-      `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
-    );
-  }
-  const parts = expr.replace(/^\.\s*/, "").split(/\./).filter(Boolean);
-  for (const part of parts) {
-    if (!/^\w+(\[\])?$/.test(part)) {
-      throw new CLIError(
-        `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
-      );
-    }
-  }
-  let current = data;
-  for (const part of parts) {
-    const arrayMatch = part.match(/^(\w+)\[\]$/);
-    if (arrayMatch) {
-      const key = arrayMatch[1];
-      if (current && typeof current === "object" && key in current) {
-        const arr = current[key];
-        if (!Array.isArray(arr)) return void 0;
-        current = arr;
-      } else {
-        return void 0;
-      }
-    } else if (Array.isArray(current)) {
-      current = current.map(
-        (item) => item && typeof item === "object" ? item[part] : void 0
-      );
-    } else if (current && typeof current === "object") {
-      current = current[part];
-    } else {
-      return void 0;
-    }
-  }
-  return current;
-}
-
 // src/api/timeouts.ts
 var API_TIMEOUT_MS = 3e4;
+var SIMULATION_POLL_TIMEOUT_MS = 6e5;
 
 // src/version.ts
 import { createRequire } from "module";
@@ -629,6 +546,20 @@ function render(data, opts, humanRenderer, listItems) {
     console.log(formatJson(data));
     return;
   }
+  if (opts.agent) {
+    if (listItems) {
+      for (const item of listItems) {
+        console.log(JSON.stringify(item));
+      }
+    } else {
+      console.log(JSON.stringify(data));
+    }
+    return;
+  }
+  if (opts.human) {
+    console.log(humanRenderer());
+    return;
+  }
   if (!process.stdout.isTTY) {
     if (listItems) {
       for (const item of listItems) {
@@ -673,7 +604,15 @@ function parseTypedFields(fields, typed) {
 
 // src/commands/api.ts
 function registerApiCommand(program) {
-  program.command("api").description("Make an authenticated API request (like gh api)").argument("<endpoint>", "API endpoint path (e.g., /articles)").option("-X, --method <method>", "HTTP method").option("-f, --field <key=value...>", "String field").option(
+  program.command("api").description("Make an authenticated API request (like gh api)").argument("<endpoint>", "API endpoint path (e.g., /articles)").addHelpText(
+    "after",
+    `
+Examples:
+  intercom api /me
+  intercom api /articles --paginate
+  intercom api /contacts -X POST -f email=test@example.com -f role=user
+  intercom api /articles/123 --jq '.title'`
+  ).option("-X, --method <method>", "HTTP method").option("-f, --field <key=value...>", "String field").option(
     "-F, --typed-field <key=value...>",
     "Typed field (bools, numbers, file reads)"
   ).option("--jq <expr>", "Filter response with jq expression").option("--json", "Output as JSON").option("--paginate", "Auto-paginate through all pages").option("--verbose", "Show full HTTP request/response").action(async function(endpoint) {
@@ -828,7 +767,6 @@ async function signup(options) {
     email_submission: {},
     sign_up_locale: "en",
     new_app_feature_flags: [
-      "synchronously-create-subscription-on-signup",
       "fin-sdk",
       "messenger-public-api"
     ]
@@ -929,6 +867,13 @@ async function findOrCreateAppPackage(baseUrl, cookies, appId, appPackageId, tim
     { timeoutMs }
   );
   if (!listResponse.ok) {
+    if (listResponse.status === 403) {
+      throw new Error(
+        `Developer Hub access denied (403). This usually means the admin email has not been verified.
+  Verify your email first: intercom auth verify-email --url <url-from-verification-email>
+  Then retry this command.`
+      );
+    }
     throw new Error(`Failed to list app packages: ${listResponse.status}`);
   }
   const data = await listResponse.json();
@@ -970,6 +915,13 @@ async function findOrCreateAppPackage(baseUrl, cookies, appId, appPackageId, tim
     { timeoutMs }
   );
   if (!createResponse.ok) {
+    if (createResponse.status === 403) {
+      throw new Error(
+        `Developer Hub access denied (403). This usually means the admin email has not been verified.
+  Verify your email first: intercom auth verify-email --url <url-from-verification-email>
+  Then retry this command.`
+      );
+    }
     throw new Error(`Failed to create app package: ${createResponse.status}`);
   }
   const created = await createResponse.json();
@@ -1244,7 +1196,14 @@ function registerVerifyEmailCommand(auth) {
 
 // src/commands/auth/index.ts
 function registerAuthCommand(program) {
-  const auth = program.command("auth").description("Manage authentication credentials");
+  const auth = program.command("auth").description("Manage authentication credentials").addHelpText(
+    "after",
+    `
+Examples:
+  intercom auth login --token <api-token>
+  intercom auth status
+  intercom auth logout`
+  );
   registerLoginCommand(auth);
   registerBootstrapCommand(auth);
   registerStatusCommand(auth);
@@ -1286,7 +1245,16 @@ function htmlToText(html) {
 
 // src/commands/articles.ts
 function registerArticlesCommand(program) {
-  const articles = program.command("articles").description("Manage help center articles");
+  const articles = program.command("articles").description("Manage help center articles").addHelpText(
+    "after",
+    `
+Examples:
+  intercom articles list
+  intercom articles get 123
+  intercom articles create -f title="Getting Started" -F body=@article.md
+  intercom articles update 123 -f state=published
+  intercom articles delete 123`
+  );
   articles.command("list").description("List help center articles").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -1409,7 +1377,15 @@ ${body}` : meta;
 
 // src/commands/contacts.ts
 function registerContactsCommand(program) {
-  const contacts = program.command("contacts").description("Manage contacts");
+  const contacts = program.command("contacts").description("Manage contacts").addHelpText(
+    "after",
+    `
+Examples:
+  intercom contacts list --limit 10
+  intercom contacts get abc123
+  intercom contacts create -f email=user@example.com -f role=user
+  intercom contacts delete abc123`
+  );
   contacts.command("list").description("List contacts").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -1586,7 +1562,14 @@ function renderConversationStream(result) {
   return parts.join("\n");
 }
 function registerConversationsCommand(program) {
-  const conversations = program.command("conversations").description("Manage conversations");
+  const conversations = program.command("conversations").description("Manage conversations").addHelpText(
+    "after",
+    `
+Examples:
+  intercom conversations list
+  intercom conversations get 123
+  intercom conversations reply 123 -f body="Thanks!" -f message_type=comment -f type=admin -f admin_id=456`
+  );
   conversations.command("list").description("List conversations").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -1657,7 +1640,14 @@ function registerConversationsCommand(program) {
 
 // src/commands/help-center.ts
 function registerHelpCenterCommand(program) {
-  const helpCenter = program.command("help-center").description("Manage help center collections");
+  const helpCenter = program.command("help-center").description("Manage help center collections").addHelpText(
+    "after",
+    `
+Examples:
+  intercom help-center list
+  intercom help-center get 123
+  intercom help-center create -f name="FAQ"`
+  );
   helpCenter.command("list").description("List help center collections").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -1752,7 +1742,14 @@ export function IntercomWidget() {
 }`;
 }
 function registerMessengerCommand(program) {
-  const messenger = program.command("messenger").description("Manage Intercom Messenger settings");
+  const messenger = program.command("messenger").description("Manage Intercom Messenger settings").addHelpText(
+    "after",
+    `
+Examples:
+  intercom messenger get
+  intercom messenger update -f alignment=right -f theme_mode=dark
+  intercom messenger snippet --format react`
+  );
   messenger.command("get").description("Get Messenger settings").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -1819,6 +1816,111 @@ function registerMessengerCommand(program) {
   });
 }
 
+// src/commands/fin.ts
+import { writeFile as writeFile2 } from "fs/promises";
+
+// src/commands/fin/procedures.ts
+import { readFile as readFile2 } from "fs/promises";
+import { basename } from "path";
+import AdmZip from "adm-zip";
+function registerProceduresCommand(fin) {
+  const procedures = fin.command("procedures").description("Manage Fin SDK procedures");
+  procedures.command("list").description("List procedures from the Fin SDK manifest").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get("/fin-sdk/manifest");
+    const manifest = result;
+    const items = manifest.procedures ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No procedures found.";
+      }
+      const rows = items.map((item) => ({
+        ID: String(item.id ?? ""),
+        NAME: String(item.name ?? "")
+      }));
+      return table({ columns: ["ID", "NAME"], rows });
+    }, items);
+  });
+  procedures.command("get <id>").description("Download a procedure by ID and print its YAML content").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const buffer = await client.getBuffer(`/fin-sdk/procedures/${id}/download`);
+    const zip = new AdmZip(buffer);
+    const entry = zip.getEntries().find((e) => e.entryName.endsWith("procedure.yaml"));
+    if (!entry) {
+      throw new Error("procedure.yaml not found in downloaded ZIP");
+    }
+    console.log(zip.readAsText(entry));
+  });
+  procedures.command("upload <file>").description("Upload a procedure file to Fin SDK").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function(filePath) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const fileContent = await readFile2(filePath);
+    const formData = new FormData();
+    const blob = new Blob([fileContent], { type: "application/x-yaml" });
+    formData.append("file_data", blob, basename(filePath));
+    const result = await client.postFormData("/fin-sdk/upload", formData);
+    render(result, opts, () => formatJson(result));
+  });
+}
+
+// src/commands/fin/data-connectors.ts
+function registerDataConnectorsCommand(fin) {
+  const dataConnectors = fin.command("data-connectors").description("Manage Fin SDK data connectors");
+  dataConnectors.command("list").description("List data connectors from the Fin SDK manifest").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get("/fin-sdk/manifest");
+    const manifest = result;
+    const items = manifest.data_connectors ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No data connectors found.";
+      }
+      const rows = items.map((item) => ({
+        ID: String(item.id ?? ""),
+        NAME: String(item.name ?? "")
+      }));
+      return table({ columns: ["ID", "NAME"], rows });
+    }, items);
+  });
+  dataConnectors.command("create").description("Create a data connector").requiredOption("-f, --field <key=value>", "Field to set (e.g. name=<name>)", (v, acc) => [...acc, v], []).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const fields = opts.field ?? [];
+    const body = {};
+    for (const f of fields) {
+      const eq = f.indexOf("=");
+      if (eq === -1) throw new Error(`Invalid field format: ${f}. Expected key=value`);
+      body[f.slice(0, eq)] = f.slice(eq + 1);
+    }
+    const result = await client.post("/fin-sdk/data-connectors", body);
+    render(
+      result,
+      opts,
+      () => detail({
+        "ID": String(result.id ?? ""),
+        "Name": String(result.name ?? ""),
+        "Status": result.status != null ? String(result.status) : void 0
+      })
+    );
+  });
+  dataConnectors.command("get <id>").description("Download a data connector by ID").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(`/fin-sdk/data-connectors/${id}/download`);
+    render(
+      result,
+      opts,
+      () => detail({
+        "ID": String(result.id ?? ""),
+        "Name": String(result.name ?? "")
+      })
+    );
+  });
+}
+
 // src/commands/fin/guidance.ts
 function registerGuidanceCommand(fin) {
   const guidance = fin.command("guidance").description("Manage Fin SDK guidance");
@@ -1847,6 +1949,169 @@ function registerGuidanceCommand(fin) {
   });
 }
 
+// src/commands/fin/attributes.ts
+function registerAttributesCommand(fin) {
+  const attributes = fin.command("attributes").description("Manage Fin SDK attributes");
+  attributes.command("list").description("List Fin SDK attributes").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get("/fin-sdk/attributes");
+    const items = Array.isArray(result) ? result : result.attributes ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No attributes found.";
+      }
+      const rows = items.map((item) => ({
+        NAME: String(item.name ?? ""),
+        TYPE: String(item.type ?? ""),
+        DESCRIPTION: String(item.description ?? "")
+      }));
+      return table({ columns: ["NAME", "TYPE", "DESCRIPTION"], rows });
+    }, items);
+  });
+}
+
+// src/commands/fin/audiences.ts
+function registerAudiencesCommand(fin) {
+  const audiences = fin.command("audiences").description("Manage Fin SDK audiences");
+  audiences.command("list").description("List Fin SDK audiences").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get("/fin-sdk/audiences");
+    const items = Array.isArray(result) ? result : result.audiences ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No audiences found.";
+      }
+      const rows = items.map((item) => ({
+        ID: String(item.id ?? ""),
+        NAME: String(item.name ?? "")
+      }));
+      return table({ columns: ["ID", "NAME"], rows });
+    }, items);
+  });
+}
+
+// src/commands/fin/workflows.ts
+function registerWorkflowsCommand(fin) {
+  const workflows = fin.command("workflows").description("Manage Fin SDK workflows");
+  workflows.command("list").description("List Fin SDK workflows").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get("/fin-sdk/workflows");
+    const items = Array.isArray(result) ? result : result.workflows ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No workflows found.";
+      }
+      const rows = items.map((item) => ({
+        ID: String(item.id ?? ""),
+        TITLE: String(item.title ?? ""),
+        STATE: String(item.state ?? ""),
+        TRIGGER: String(item.trigger_type ?? "")
+      }));
+      return table({ columns: ["ID", "TITLE", "STATE", "TRIGGER"], rows });
+    }, items);
+  });
+  workflows.command("get <id>").description("Get a workflow by ID").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(`/fin-sdk/workflows/${id}`);
+    const r = result;
+    render(
+      result,
+      opts,
+      () => detail({
+        "ID": String(r.id ?? ""),
+        "Title": String(r.title ?? ""),
+        "State": String(r.state ?? ""),
+        "Trigger": r.trigger_type != null ? String(r.trigger_type) : void 0
+      })
+    );
+  });
+}
+
+// src/commands/fin/simulations.ts
+function registerSimulationsCommand(fin) {
+  const simulations = fin.command("simulations").description("Manage Fin SDK simulations");
+  simulations.command("list <procedure_id>").description("List simulations for a procedure (displays YAML)").option("--verbose", "Show HTTP request/response details").action(async function(procedureId) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const text = await client.getText(`/fin-sdk/procedures/${procedureId}/simulations`);
+    console.log(text);
+  });
+  simulations.command("run <procedure_id> [test_id]").description("Run one or all simulations for a procedure").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function(procedureId, testId) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    let result;
+    if (testId) {
+      result = await client.post(`/fin-sdk/procedures/${procedureId}/simulations/${testId}/run`, {});
+    } else {
+      result = await client.post(`/fin-sdk/procedures/${procedureId}/simulations/run`, {});
+    }
+    const r = result;
+    render(result, opts, () => {
+      if (r.enqueued && Array.isArray(r.enqueued) && r.enqueued.length > 0) {
+        const rows = r.enqueued.map((e) => ({
+          RUN_ID: String(e.run_id ?? ""),
+          TEST_ID: String(e.test_id ?? ""),
+          NAME: String(e.simulation_name ?? ""),
+          STATUS: String(e.status ?? "")
+        }));
+        return table({ columns: ["RUN_ID", "TEST_ID", "NAME", "STATUS"], rows });
+      } else {
+        const runId = r.run_id;
+        if (runId !== void 0) {
+          return `run_id: ${runId}`;
+        } else {
+          return detail({
+            "Procedure ID": String(r.procedure_id ?? "")
+          });
+        }
+      }
+    });
+  });
+  simulations.command("result <run_id>").description("Get the result of a simulation run").option("--json", "Output as JSON").option("--wait", "Poll until run completes").option("--verbose", "Show HTTP request/response details").action(async function(runId) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    let result = await client.get(`/fin-sdk/runs/${runId}`);
+    if (opts.wait) {
+      const deadline = Date.now() + SIMULATION_POLL_TIMEOUT_MS;
+      while (result.status === "pending" || result.status === "running") {
+        if (Date.now() > deadline) {
+          throw new TimeoutError(
+            `Simulation polling timed out after ${SIMULATION_POLL_TIMEOUT_MS / 1e3}s. Last status: ${result.status}. Run "intercom fin simulations result ${runId}" to check later.`
+          );
+        }
+        await new Promise((r) => setTimeout(r, 2e3));
+        result = await client.get(`/fin-sdk/runs/${runId}`);
+      }
+    }
+    render(
+      result,
+      opts,
+      () => detail({
+        "Run ID": String(result.run_id ?? ""),
+        "Status": String(result.status ?? "")
+      })
+    );
+  });
+  simulations.command("generate <procedure_id>").description("Generate simulations for a procedure").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function(procedureId) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.post(`/fin-sdk/procedures/${procedureId}/simulations/generate`, {});
+    const r = result;
+    render(
+      result,
+      opts,
+      () => detail({
+        "Status": String(r.status ?? ""),
+        "Procedure ID": String(r.procedure_id ?? "")
+      })
+    );
+  });
+}
+
 // src/auth/ember-session.ts
 async function getEmberSession(options) {
   const { email, password, appId, verifyEmailUrl, timeoutMs = API_TIMEOUT_MS } = options;
@@ -2017,7 +2282,14 @@ function renderResourceTable(label, items) {
 ${table({ columns: ["ID", "NAME"], rows })}`;
 }
 function registerFinCommand(program) {
-  const fin = program.command("fin").description("Manage Fin SDK resources");
+  const fin = program.command("fin").description("Manage Fin AI Agent and SDK resources").addHelpText(
+    "after",
+    `
+Examples:
+  intercom fin manifest
+  intercom fin enable --email admin@company.com
+  intercom fin guidance list`
+  );
   fin.command("manifest").description("Show the Fin SDK manifest for this workspace").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
@@ -2043,12 +2315,26 @@ function registerFinCommand(program) {
     });
   });
   registerFinEnableCommand(fin);
+  registerProceduresCommand(fin);
+  registerDataConnectorsCommand(fin);
   registerGuidanceCommand(fin);
+  registerAttributesCommand(fin);
+  registerAudiencesCommand(fin);
+  registerWorkflowsCommand(fin);
+  registerSimulationsCommand(fin);
+  fin.command("download").description("Download Fin SDK resources as a ZIP file").option("-o, --output <path>", "Output file path", "./fin-resources.zip").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const outputPath = opts.output ?? "./fin-resources.zip";
+    const client = await resolveClient(opts);
+    const buffer = await client.getBuffer("/fin-sdk/download");
+    await writeFile2(outputPath, buffer);
+    console.log(`Downloaded ${buffer.length} bytes to ${outputPath}`);
+  });
 }
 
 // src/commands/setup.ts
 import { readdirSync, readFileSync as readFileSync3, statSync } from "fs";
-import { join as join3, basename } from "path";
+import { join as join3, basename as basename2 } from "path";
 function isGreenfield(opts) {
   return !!(opts.email && opts.name && (process.env.INTERCOM_PASSWORD || opts.passwordStdin));
 }
@@ -2056,6 +2342,11 @@ function hasPartialGreenfieldFlags(opts) {
   const hasPassword = !!(process.env.INTERCOM_PASSWORD || opts.passwordStdin);
   return !!(opts.email && hasPassword && !opts.name);
 }
+async function hasExistingAuth() {
+  const configDir = process.env.INTERCOM_CONFIG_DIR;
+  const config = await readConfig(configDir);
+  return !!config.default;
+}
 function buildPlan(opts) {
   const steps = [];
   let stepNum = 1;
@@ -2101,8 +2392,8 @@ function buildPlan(opts) {
     }
     if (mdFiles.length > 0) {
       const articleCommands = mdFiles.map((file) => {
-        const title = basename(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-        return `intercom articles create -f title="${title}" -F body=@${join3(opts.articlesFrom, file)}`;
+        const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        return `intercom articles create -f title="${title}" -F body=@${join3(opts.articlesFrom, file)} -f author_id=$(intercom me --json | jq -r .id)`;
       });
       steps.push({
         step: stepNum++,
@@ -2114,7 +2405,7 @@ function buildPlan(opts) {
         step: stepNum++,
         description: `Create articles from ${opts.articlesFrom}`,
         commands: [
-          `intercom articles create -f title="<article-title>" -F body=@${opts.articlesFrom}/<file>.md`
+          `intercom articles create -f title="<article-title>" -F body=@${opts.articlesFrom}/<file>.md -f author_id=$(intercom me --json | jq -r .id)`
         ]
       });
     }
@@ -2140,15 +2431,20 @@ function formatPlanText(steps) {
 }
 async function runPostAuthSteps(client, opts, results, appId) {
   results.push(`\u2713 Messenger configured`);
+  const me = await client.get("/me");
+  const authorId = me.id != null ? Number(me.id) : void 0;
   const helpCenterName = opts.companyName ? `${opts.companyName} Help` : "Help Center";
   const collections = await client.paginate("/help_center/collections");
   const existingCollection = collections.find(
     (c) => String(c.name ?? "") === helpCenterName
   );
+  let collectionId;
   if (existingCollection) {
+    collectionId = String(existingCollection.id);
     results.push(`\u2713 Help center already exists (${helpCenterName})`);
   } else {
-    await client.post("/help_center/collections", { name: helpCenterName });
+    const created = await client.post("/help_center/collections", { name: helpCenterName });
+    collectionId = created.id != null ? String(created.id) : void 0;
     results.push(`\u2713 Help center created (${helpCenterName})`);
   }
   if (opts.articlesFrom) {
@@ -2163,12 +2459,18 @@ async function runPostAuthSteps(client, opts, results, appId) {
     let created = 0;
     let skipped = 0;
     for (const file of mdFiles) {
-      const title = basename(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+      const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
       const body = readFileSync3(join3(opts.articlesFrom, file), "utf-8");
       if (existingTitles.has(title)) {
         skipped++;
       } else {
-        await client.post("/articles", { title, body, state: "published" });
+        const articleBody = { title, body, state: "published" };
+        if (authorId != null) articleBody.author_id = authorId;
+        if (collectionId != null) {
+          articleBody.parent_id = collectionId;
+          articleBody.parent_type = "collection";
+        }
+        await client.post("/articles", articleBody);
         created++;
       }
     }
@@ -2270,7 +2572,19 @@ async function runPostAuthSteps(client, opts, results, appId) {
   console.log("Setup complete!");
 }
 function registerSetupCommand(program) {
-  program.command("setup").description("Set up a complete Intercom installation").option("--company-name <name>", "Company name for Messenger branding").option("--articles-from <dir>", "Directory of markdown files to create as articles").option("--plan", "Output setup steps as CLI commands without executing").option("--dry-run", "Show what would happen without executing").option("--json", "Output as JSON (for --plan mode)").option("--verbose", "Show HTTP request/response details").option("--email <email>", "Admin email address (for new workspace signup)").option("--password-stdin", "Read password from stdin (or set INTERCOM_PASSWORD env var)").option("--name <name>", "Admin name (for new workspace signup)").option("--plan-tier <tier>", "Trial plan tier: essential, advanced, expert (default: advanced)").option("--enable-fin", "Enable Fin AI Agent (default: true for greenfield setup)", true).option("--no-enable-fin", "Skip Fin enablement").option("--verify-email-url <url>", "Email verification URL (needed for Fin on fresh workspaces)").action(async function() {
+  program.command("setup").description("Set up a complete Intercom installation").addHelpText(
+    "after",
+    `
+Examples:
+  # Existing workspace (already authenticated)
+  intercom setup --company-name "Acme Inc" --articles-from ./docs
+
+  # New workspace (greenfield)
+  INTERCOM_PASSWORD=*** intercom setup --email admin@acme.com --name "Admin" --company-name "Acme Inc"
+
+  # Preview steps without executing
+  intercom setup --plan`
+  ).option("--company-name <name>", "Company name for Messenger branding").option("--articles-from <dir>", "Directory of markdown files to create as articles").option("--plan", "Output setup steps as CLI commands without executing").option("--dry-run", "Show what would happen without executing").option("--json", "Output as JSON (for --plan mode)").option("--verbose", "Show HTTP request/response details").option("--email <email>", "Admin email address (for new workspace signup)").option("--password-stdin", "Read password from stdin (or set INTERCOM_PASSWORD env var)").option("--name <name>", "Admin name (for new workspace signup)").option("--plan-tier <tier>", "Trial plan tier: essential, advanced, expert (default: advanced)").option("--enable-fin", "Enable Fin AI Agent (default: true for greenfield setup)", true).option("--no-enable-fin", "Skip Fin enablement").option("--verify-email-url <url>", "Email verification URL (needed for Fin on fresh workspaces)").action(async function() {
     const opts = this.optsWithGlobals();
     if (hasPartialGreenfieldFlags(opts)) {
       throw new CLIError(
@@ -2321,7 +2635,8 @@ function registerSetupCommand(program) {
       return;
     }
     const results = [];
-    if (isGreenfield(opts)) {
+    const alreadyAuthed = await hasExistingAuth();
+    if (isGreenfield(opts) && !alreadyAuthed) {
       const password = await resolvePassword({ passwordStdin: opts.passwordStdin });
       const baseUrl = getAppBaseUrl();
       const planTier = opts.planTier ?? "advanced";
@@ -2335,6 +2650,13 @@ function registerSetupCommand(program) {
         plan: planTier
       });
       results.push(`\u2713 Workspace created: ${workspace.name} (${workspace.id})`);
+      if (opts.verifyEmailUrl) {
+        try {
+          await fetchWithTimeout(opts.verifyEmailUrl, { redirect: "manual" }, { timeoutMs: API_TIMEOUT_MS });
+          results.push(`\u2713 Email verified`);
+        } catch {
+        }
+      }
       let token;
       try {
         const result = await getToken({
@@ -2349,9 +2671,17 @@ function registerSetupCommand(program) {
         console.error(`\u2713 Workspace created: ${workspace.name} (${workspace.id})`);
         console.error(`
 Authentication failed after workspace creation: ${message}`);
-        console.error(`
+        if (message.includes("403")) {
+          console.error(`
+This is likely because the email has not been verified.`);
+          console.error(`Verify your email first, then bootstrap:`);
+          console.error(`  intercom auth verify-email --url <url-from-verification-email>`);
+        } else {
+          console.error(`
 Your workspace exists but credentials were not saved.`);
-        console.error(`To complete setup, run:
+        }
+        console.error(`
+To complete setup, run:
 `);
         console.error(`  INTERCOM_PASSWORD=*** intercom auth bootstrap --email ${opts.email} --app-id ${workspace.id}`);
         console.error(`
@@ -2385,20 +2715,246 @@ Then re-run setup without signup flags:
   });
 }
 
+// src/commands/completion.ts
+function binName() {
+  const argv1 = process.argv[1] ?? "";
+  if (argv1.endsWith("/fin") || argv1.endsWith("\\fin")) return "fin";
+  return "intercom";
+}
+var COMMANDS = {
+  api: [],
+  auth: ["login", "logout", "status", "bootstrap", "signup", "verify-email"],
+  me: [],
+  articles: ["list", "get", "create", "update", "delete"],
+  contacts: ["list", "get", "create", "update", "delete"],
+  conversations: ["list", "get", "reply"],
+  "help-center": ["list", "get", "create"],
+  messenger: ["get", "update", "snippet"],
+  fin: ["manifest", "enable", "guidance"],
+  setup: [],
+  pricing: [],
+  completion: ["bash", "zsh", "fish"]
+};
+var GLOBAL_FLAGS = [
+  "--json",
+  "--jq",
+  "--workspace",
+  "--verbose",
+  "--no-retry",
+  "--timeout",
+  "--agent",
+  "--human",
+  "--help",
+  "--version"
+];
+function bashScript(name = binName()) {
+  const commandNames = Object.keys(COMMANDS).join(" ");
+  const fnName = `_${name}`;
+  const subcommandCases = Object.entries(COMMANDS).filter(([, subs]) => subs.length > 0).map(([cmd, subs]) => `      ${cmd}) COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") ) ;;`).join("\n");
+  return `# bash completion for ${name} CLI
+# Add to ~/.bashrc: eval "$(${name} completion bash)"
+
+${fnName}() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  commands="${commandNames}"
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(" ")}" -- "$cur") )
+    return 0
+  fi
+
+  case "\${COMP_WORDS[1]}" in
+${subcommandCases}
+    *)
+      if [[ \${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+      fi
+      ;;
+  esac
+  return 0
+}
+
+complete -F ${fnName} ${name}
+`;
+}
+function zshScript(name = binName()) {
+  const fnName = `_${name}`;
+  const commandDescs = [
+    "api:'Make an authenticated API request'",
+    "auth:'Manage authentication credentials'",
+    "me:'Show current admin and workspace info'",
+    "articles:'Manage help center articles'",
+    "contacts:'Manage contacts'",
+    "conversations:'Manage conversations'",
+    "help-center:'Manage help center collections'",
+    "messenger:'Manage Messenger settings'",
+    "fin:'Manage Fin AI Agent'",
+    "setup:'Set up a complete Intercom installation'",
+    "pricing:'Show current Intercom pricing information'",
+    "completion:'Generate shell completion scripts'"
+  ];
+  const subcommandFunctions = Object.entries(COMMANDS).filter(([, subs]) => subs.length > 0).map(([cmd, subs]) => {
+    const subFnName = cmd.replace(/-/g, "_");
+    const subLines = subs.map((s) => `'${s}'`).join(" ");
+    return `${fnName}_${subFnName}() {
+  local -a subcommands
+  subcommands=(${subLines})
+  _describe 'subcommand' subcommands
+}`;
+  }).join("\n\n");
+  return `#compdef ${name}
+# zsh completion for ${name} CLI
+# Add to ~/.zshrc: eval "$(${name} completion zsh)"
+
+${fnName}() {
+  local -a commands global_flags
+  commands=(
+    ${commandDescs.join("\n    ")}
+  )
+  global_flags=(
+    ${GLOBAL_FLAGS.map((f) => `'${f}'`).join("\n    ")}
+  )
+
+  _arguments -C \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      case $words[1] in
+${Object.entries(COMMANDS).filter(([, subs]) => subs.length > 0).map(([cmd]) => `        ${cmd}) ${fnName}_${cmd.replace(/-/g, "_")} ;;`).join("\n")}
+      esac
+      ;;
+  esac
+}
+
+${subcommandFunctions}
+
+${fnName} "$@"
+`;
+}
+function fishScript(name = binName()) {
+  const lines = [
+    `# fish completion for ${name} CLI`,
+    `# Add to fish config: ${name} completion fish | source`,
+    "",
+    "# Disable file completions",
+    `complete -c ${name} -f`,
+    "",
+    "# Top-level commands"
+  ];
+  const commandDescs = {
+    api: "Make an authenticated API request",
+    auth: "Manage authentication credentials",
+    me: "Show current admin and workspace info",
+    articles: "Manage help center articles",
+    contacts: "Manage contacts",
+    conversations: "Manage conversations",
+    "help-center": "Manage help center collections",
+    messenger: "Manage Messenger settings",
+    fin: "Manage Fin AI Agent",
+    setup: "Set up a complete Intercom installation",
+    pricing: "Show current Intercom pricing information",
+    completion: "Generate shell completion scripts"
+  };
+  for (const [cmd, desc] of Object.entries(commandDescs)) {
+    lines.push(
+      `complete -c ${name} -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'`
+    );
+  }
+  lines.push("");
+  lines.push("# Subcommands");
+  for (const [cmd, subs] of Object.entries(COMMANDS)) {
+    for (const sub of subs) {
+      lines.push(
+        `complete -c ${name} -n '__fish_seen_subcommand_from ${cmd}' -a '${sub}'`
+      );
+    }
+  }
+  lines.push("");
+  lines.push("# Global flags");
+  for (const flag of GLOBAL_FLAGS) {
+    lines.push(`complete -c ${name} -l '${flag.replace(/^--/, "")}'`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function registerCompletionCommand(program) {
+  const name = binName();
+  const completion = program.command("completion").description("Generate shell completion scripts").addHelpText(
+    "after",
+    `
+Examples:
+  # Bash (add to ~/.bashrc)
+  eval "$(${name} completion bash)"
+
+  # Zsh (add to ~/.zshrc)
+  eval "$(${name} completion zsh)"
+
+  # Fish (add to fish config)
+  ${name} completion fish | source`
+  );
+  completion.command("bash").description("Generate bash completion script").action(() => {
+    console.log(bashScript());
+  });
+  completion.command("zsh").description("Generate zsh completion script").action(() => {
+    console.log(zshScript());
+  });
+  completion.command("fish").description("Generate fish completion script").action(() => {
+    console.log(fishScript());
+  });
+}
+
+// src/commands/pricing.ts
+var PRICING_URL = "https://www.intercom.com/pricing.md";
+function registerPricingCommand(program) {
+  program.command("pricing").description("Show current Intercom pricing information").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
+    const opts = this.optsWithGlobals();
+    const response = await fetchWithTimeout(
+      PRICING_URL,
+      { headers: { Accept: "text/markdown, text/plain, */*" } },
+      { timeoutMs: API_TIMEOUT_MS, verbose: opts.verbose }
+    );
+    if (!response.ok) {
+      throw new CLIError(`Failed to fetch pricing: ${response.status} ${response.statusText}`);
+    }
+    const markdown = await response.text();
+    if (opts.json) {
+      const { formatJson: formatJson2 } = await import("./json-TDEGGEUF.js");
+      console.log(formatJson2({ url: PRICING_URL, content: markdown }));
+    } else {
+      console.log(markdown);
+    }
+  });
+}
+
 // src/index.ts
+function detectBinaryName() {
+  const argv1 = process.argv[1] ?? "";
+  if (argv1.endsWith("/fin") || argv1.endsWith("\\fin")) return "fin";
+  return "intercom";
+}
 function fullCommandName(cmd) {
   const parts = [];
+  const rootNames = /* @__PURE__ */ new Set(["intercom", "fin"]);
   let current = cmd;
   while (current) {
     const name = current.name();
-    if (name && name !== "intercom") parts.unshift(name);
+    if (name && !rootNames.has(name)) parts.unshift(name);
     current = current.parent;
   }
   return parts.join(" ");
 }
 function createProgram() {
   const program = new Command();
-  program.name("intercom").description("CLI tool for managing Intercom workspaces").version(VERSION).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output").option("--workspace <id>", "Override default workspace").option("--verbose", "Show HTTP request/response details").option("--no-retry", "Disable automatic rate limit retry").option("--timeout <seconds>", "Request timeout in seconds");
+  const binName2 = detectBinaryName();
+  program.name(binName2).description("CLI tool for managing Intercom workspaces").version(VERSION).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output").option("--workspace <id>", "Override default workspace").option("--verbose", "Show HTTP request/response details").option("--no-retry", "Disable automatic rate limit retry").option("--timeout <seconds>", "Request timeout in seconds").option("--agent", "Force machine-readable output (JSON/NDJSON)").option("--human", "Force human-readable output even when piped");
   registerApiCommand(program);
   registerAuthCommand(program);
   registerMeCommand(program);
@@ -2409,13 +2965,19 @@ function createProgram() {
   registerMessengerCommand(program);
   registerFinCommand(program);
   registerSetupCommand(program);
-  program.hook("preAction", (_, actionCommand) => {
+  registerPricingCommand(program);
+  registerCompletionCommand(program);
+  program.hook("preAction", (thisCommand, actionCommand) => {
+    const rootOpts = thisCommand.opts();
+    if (rootOpts.agent && rootOpts.human) {
+      throw new CLIError("--agent and --human are mutually exclusive");
+    }
     setCliCommand(fullCommandName(actionCommand));
   });
   return program;
 }
 function handleError(err) {
-  const isJson = process.argv.includes("--json");
+  const isJson = process.argv.includes("--json") || process.argv.includes("--agent");
   if (err instanceof CLIError) {
     if (isJson) {
       console.error(formatJson({
@@ -2433,7 +2995,7 @@ function handleError(err) {
   console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
   process.exit(1);
 }
-var isMainModule = process.argv[1]?.endsWith("index.js") || process.argv[1]?.endsWith("intercom");
+var isMainModule = process.argv[1]?.endsWith("index.js") || process.argv[1]?.endsWith("intercom") || process.argv[1]?.endsWith("fin");
 if (isMainModule) {
   const program = createProgram();
   try {