@intercom/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -9,11 +9,14 @@ import {
   applyJq,
   detectAuthType,
   formatJson
-} from "./chunk-QEXGKXTU.js";
+} from "./chunk-Y4JK5AHH.js";
 
 // src/index.ts
 import { Command } from "commander";
 
+// src/commands/api.ts
+import { readFileSync as readFileSync3 } from "fs";
+
 // src/api/timeouts.ts
 var API_TIMEOUT_MS = 3e4;
 var SIMULATION_POLL_TIMEOUT_MS = 6e5;
@@ -163,6 +166,22 @@ var IntercomClient = class {
           retryAfter
         );
       }
+      const RETRYABLE_5XX = [502, 503, 504];
+      if (RETRYABLE_5XX.includes(response.status)) {
+        if (attempt < this.maxRetries) {
+          const backoffMs = Math.pow(2, attempt) * 1e3;
+          if (this.verbose) {
+            console.error(
+              `Server error ${response.status}. Retrying in ${backoffMs / 1e3}s (attempt ${attempt + 1}/${this.maxRetries})...`
+            );
+          }
+          await new Promise((r) => setTimeout(r, backoffMs));
+          continue;
+        }
+        throw new CLIError(
+          `Server error ${response.status} after ${this.maxRetries} retries: ${errorMsg}`
+        );
+      }
       throw new CLIError(errorMsg);
     }
     throw new CLIError("Request failed after retries");
@@ -392,9 +411,9 @@ var FallbackBackend = class {
     }
   }
 };
-function createDefaultBackend(configDir) {
-  if (configDir) {
-    return new EncryptedFileBackend(configDir);
+function createDefaultBackend(configDir2) {
+  if (configDir2) {
+    return new EncryptedFileBackend(configDir2);
   }
   return new FallbackBackend(
     new NativeKeychainBackend(),
@@ -433,8 +452,8 @@ var CONFIG_FILE = "config.json";
 function defaultConfigDir() {
   return join2(homedir2(), ".intercom");
 }
-async function readConfig(configDir) {
-  const dir = configDir ?? defaultConfigDir();
+async function readConfig(configDir2) {
+  const dir = configDir2 ?? defaultConfigDir();
   try {
     const raw = await readFile(join2(dir, CONFIG_FILE), "utf-8");
     return JSON.parse(raw);
@@ -442,27 +461,27 @@ async function readConfig(configDir) {
     return { workspaces: {} };
   }
 }
-async function writeConfig(config, configDir) {
-  const dir = configDir ?? defaultConfigDir();
+async function writeConfig(config, configDir2) {
+  const dir = configDir2 ?? defaultConfigDir();
   await mkdir(dir, { recursive: true });
   await atomicWriteFile(join2(dir, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
 }
-async function addWorkspace(configDir, workspace) {
-  const config = await readConfig(configDir);
+async function addWorkspace(configDir2, workspace) {
+  const config = await readConfig(configDir2);
   config.workspaces[workspace.app_id] = workspace;
   if (!config.default) {
     config.default = workspace.app_id;
   }
-  await writeConfig(config, configDir);
+  await writeConfig(config, configDir2);
 }
-async function removeWorkspace(configDir, appId) {
-  const config = await readConfig(configDir);
+async function removeWorkspace(configDir2, appId) {
+  const config = await readConfig(configDir2);
   delete config.workspaces[appId];
   if (config.default === appId) {
     const remaining = Object.keys(config.workspaces);
     config.default = remaining.length > 0 ? remaining[0] : void 0;
   }
-  await writeConfig(config, configDir);
+  await writeConfig(config, configDir2);
 }
 
 // src/commands/helpers.ts
@@ -479,8 +498,8 @@ async function resolveClient(options = {}) {
       timeoutMs: options.timeout ? parseInt(options.timeout, 10) * 1e3 : void 0
     });
   }
-  const configDir = process.env.INTERCOM_CONFIG_DIR;
-  const config = await readConfig(configDir);
+  const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+  const config = await readConfig(configDir2);
   const appId = options.workspace ?? config.default;
   if (!appId) {
     throw new AuthError(
@@ -492,7 +511,7 @@ async function resolveClient(options = {}) {
       `Default workspace "${appId}" is not in configured workspaces. Run "intercom auth bootstrap" or "intercom auth login --token <token>" to re-authenticate.`
     );
   }
-  const store = new CredentialStore(createDefaultBackend(configDir));
+  const store = new CredentialStore(createDefaultBackend(configDir2));
   const cred = await store.get(appId);
   if (!cred) {
     throw new AuthError(
@@ -603,6 +622,20 @@ function parseTypedFields(fields, typed) {
 }
 
 // src/commands/api.ts
+function readInput(input) {
+  let raw;
+  if (input === "-") {
+    const fd = readFileSync3(0, "utf-8");
+    raw = fd;
+  } else {
+    raw = readFileSync3(input, "utf-8");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CLIError(`Failed to parse JSON from ${input === "-" ? "stdin" : input}`);
+  }
+}
 function registerApiCommand(program) {
   program.command("api").description("Make an authenticated API request (like gh api)").argument("<endpoint>", "API endpoint path (e.g., /articles)").addHelpText(
     "after",
@@ -615,16 +648,18 @@ Examples:
   ).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) {
+  ).option("--jq <expr>", "Filter response with jq expression").option("--json", "Output as JSON").option("--input <file>", "Read JSON body from file (use - for stdin)").option("--paginate", "Auto-paginate through all pages").option("--verbose", "Show full HTTP request/response").action(async function(endpoint) {
     const options = this.optsWithGlobals();
     const client = await resolveClient(options);
     const stringFields = options.field ?? [];
     const typedFields = options.typedField ?? [];
+    const inputBody = options.input ? readInput(options.input) : {};
     const body = {
+      ...inputBody,
       ...parseTypedFields(stringFields, false),
       ...parseTypedFields(typedFields, true)
     };
-    const hasBody = stringFields.length > 0 || typedFields.length > 0;
+    const hasBody = stringFields.length > 0 || typedFields.length > 0 || !!options.input;
     const method = options.method ?? (hasBody ? "POST" : "GET");
     let result;
     if (options.paginate && method.toUpperCase() === "GET") {
@@ -668,7 +703,14 @@ Examples:
 
 // src/commands/auth/login.ts
 function registerLoginCommand(auth) {
-  auth.command("login").description("Authenticate with Intercom").option("--token <token>", "Authenticate with an API key or token directly").option("--device", "Use device flow (for headless environments)").action(async (options) => {
+  auth.command("login").description("Authenticate with Intercom").option("--token <token>", "Authenticate with an API key or token directly").option("--device", "Use device flow (for headless environments)").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom auth login --token <your-api-token>
+
+Environment: Set INTERCOM_TOKEN to skip login entirely.`
+  ).action(async (options) => {
     if (options.token) {
       await loginWithToken(options.token);
     } else if (options.device) {
@@ -692,17 +734,17 @@ async function loginWithToken(token) {
   const app = me.app;
   const appId = app?.id_code ?? me.id;
   const name = app?.name ?? "Unknown";
-  const configDir = process.env.INTERCOM_CONFIG_DIR;
-  const store = new CredentialStore(createDefaultBackend(configDir));
+  const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+  const store = new CredentialStore(createDefaultBackend(configDir2));
   await store.set(appId, { token, auth_type: authType, app_id: appId });
-  await addWorkspace(configDir, { app_id: appId, name });
+  await addWorkspace(configDir2, { app_id: appId, name });
   console.log(`Authenticated to ${name} (${appId})`);
 }
 
 // src/auth/cookies.ts
 function extractCookies(response) {
   const setCookies = typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : (response.headers.get("set-cookie") ?? "").split(/,(?=[^ ])/).filter(Boolean);
-  return setCookies.map((c) => c.split(";")[0]).join("; ");
+  return setCookies.map((c2) => c2.split(";")[0]).join("; ");
 }
 function mergeCookies(existing, newCookies) {
   const map = /* @__PURE__ */ new Map();
@@ -1026,10 +1068,10 @@ function registerBootstrapCommand(auth) {
         console.log(`Found app package: ${appPackage.name} (id: ${appPackage.id})`);
       }
       console.log("Access token acquired");
-      const configDir = process.env.INTERCOM_CONFIG_DIR;
-      const store = new CredentialStore(createDefaultBackend(configDir));
+      const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+      const store = new CredentialStore(createDefaultBackend(configDir2));
       await store.set(appId, { token, auth_type: "oauth", app_id: appId });
-      await addWorkspace(configDir, { app_id: appId, name: appId });
+      await addWorkspace(configDir2, { app_id: appId, name: appId });
       console.log(`
 Authenticated to workspace ${appId}`);
     } catch (err) {
@@ -1041,15 +1083,85 @@ Authenticated to workspace ${appId}`);
 }
 
 // src/output/formatter.ts
+import pc from "picocolors";
+function isColorEnabled() {
+  return !!process.stdout.isTTY && !process.env.NO_COLOR;
+}
+function c(fn, s) {
+  return isColorEnabled() ? fn(s) : s;
+}
+var STATUS_COLORS = {
+  // green
+  active: pc.green,
+  open: pc.green,
+  published: pc.green,
+  enabled: pc.green,
+  verified: pc.green,
+  true: pc.green,
+  // red
+  error: pc.red,
+  closed: pc.red,
+  deleted: pc.red,
+  disabled: pc.red,
+  false: pc.red,
+  // yellow
+  pending: pc.yellow,
+  draft: pc.yellow,
+  snoozed: pc.yellow
+};
+function colorizeStatus(value) {
+  if (!isColorEnabled()) return value;
+  const fn = STATUS_COLORS[value.toLowerCase()];
+  return fn ? fn(value) : value;
+}
+function truncate(value, max) {
+  if (value.length <= max) return value;
+  return value.slice(0, max - 1) + "\u2026";
+}
+var DEFAULT_MAX_COLUMNS = 8;
+var DEFAULT_TRUNCATION = 50;
+var WIDE_TRUNCATION = 200;
+var STATUS_KEYS = /* @__PURE__ */ new Set([
+  "STATE",
+  "STATUS",
+  "OPEN",
+  "ROLE",
+  "ENABLED"
+]);
+function isWide() {
+  return process.argv.includes("--wide");
+}
 function table({ columns, rows }) {
   if (rows.length === 0) return "";
-  const widths = columns.map(
-    (col) => Math.max(col.length, ...rows.map((row) => (row[col] ?? "").length))
+  const wide = isWide();
+  const maxTrunc = wide ? WIDE_TRUNCATION : DEFAULT_TRUNCATION;
+  const displayColumns = wide ? columns : columns.slice(0, DEFAULT_MAX_COLUMNS);
+  const truncatedRows = rows.map((row) => {
+    const out = {};
+    for (const col of displayColumns) {
+      out[col] = truncate(row[col] ?? "", maxTrunc);
+    }
+    return out;
+  });
+  const widths = displayColumns.map(
+    (col) => Math.max(
+      col.length,
+      ...truncatedRows.map((row) => (row[col] ?? "").length)
+    )
   );
-  const formatRow = (values) => values.map((val, i) => i < values.length - 1 ? val.padEnd(widths[i]) : val).join("  ");
-  const header = formatRow(columns);
-  const body = rows.map(
-    (row) => formatRow(columns.map((col) => row[col] ?? ""))
+  const formatRow = (values, isHeader) => values.map((val, i) => {
+    const col = displayColumns[i];
+    const padded = i < values.length - 1 ? val.padEnd(widths[i]) : val;
+    if (isHeader) return c(pc.bold, padded);
+    if (STATUS_KEYS.has(col)) return colorizeStatus(padded);
+    return padded;
+  }).join("  ");
+  const header = formatRow(displayColumns, true);
+  const body = truncatedRows.map(
+    (row) => formatRow(
+      displayColumns.map((col) => row[col] ?? ""),
+      false
+    )
   );
   return [header, ...body].join("\n");
 }
@@ -1059,19 +1171,25 @@ function detail(data) {
   );
   if (entries.length === 0) return "";
   const maxKeyLen = Math.max(...entries.map(([k]) => k.length));
-  return entries.map(([key, value]) => `${key.padEnd(maxKeyLen)}:  ${value}`).join("\n");
+  return entries.map(([key, value]) => {
+    const label = c(pc.bold, key.padEnd(maxKeyLen));
+    const strVal = String(value);
+    const isStatus = STATUS_KEYS.has(key.toUpperCase());
+    const colored = isStatus ? colorizeStatus(strVal) : strVal;
+    return `${label}:  ${colored}`;
+  }).join("\n");
 }
 
 // src/commands/auth/status.ts
 function registerStatusCommand(auth) {
   auth.command("status").description("Show current authentication status").option("--json", "Output as JSON").action(async (options) => {
-    const configDir = process.env.INTERCOM_CONFIG_DIR;
-    const config = await readConfig(configDir);
+    const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+    const config = await readConfig(configDir2);
     const appId = config.default;
     if (!appId) {
       throw new AuthError('Not authenticated. Run "intercom auth login" to get started.');
     }
-    const store = new CredentialStore(createDefaultBackend(configDir));
+    const store = new CredentialStore(createDefaultBackend(configDir2));
     const cred = await store.get(appId);
     if (!cred) {
       throw new AuthError('Not authenticated. Run "intercom auth login" to get started.');
@@ -1098,15 +1216,15 @@ function registerStatusCommand(auth) {
 // src/commands/auth/logout.ts
 function registerLogoutCommand(auth) {
   auth.command("logout").description("Remove stored credentials").option("--workspace <id>", "Workspace app_id to log out of").action(async (options) => {
-    const configDir = process.env.INTERCOM_CONFIG_DIR;
-    const config = await readConfig(configDir);
+    const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+    const config = await readConfig(configDir2);
     const appId = options.workspace ?? config.default;
     if (!appId) {
       throw new AuthError("Not authenticated.");
     }
-    const store = new CredentialStore(createDefaultBackend(configDir));
+    const store = new CredentialStore(createDefaultBackend(configDir2));
     await store.delete(appId);
-    await removeWorkspace(configDir, appId);
+    await removeWorkspace(configDir2, appId);
     const name = config.workspaces[appId]?.name ?? appId;
     console.log(`Logged out of ${name} (${appId})`);
   });
@@ -1145,10 +1263,10 @@ function registerSignupCommand(auth) {
           password,
           appId: workspace.id
         });
-        const configDir = process.env.INTERCOM_CONFIG_DIR;
-        const store = new CredentialStore(createDefaultBackend(configDir));
+        const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+        const store = new CredentialStore(createDefaultBackend(configDir2));
         await store.set(appId, { token, auth_type: "oauth", app_id: appId });
-        await addWorkspace(configDir, { app_id: appId, name: workspace.name });
+        await addWorkspace(configDir2, { app_id: appId, name: workspace.name });
         console.log(`
 Authenticated to workspace ${appId}`);
       } catch {
@@ -1194,6 +1312,64 @@ function registerVerifyEmailCommand(auth) {
   });
 }
 
+// src/commands/auth/list.ts
+function registerListCommand(auth) {
+  auth.command("list").description("List all configured workspaces").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").action(async function() {
+    const opts = this.optsWithGlobals();
+    const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+    const config = await readConfig(configDir2);
+    const store = new CredentialStore(createDefaultBackend(configDir2));
+    const workspaces = await Promise.all(
+      Object.values(config.workspaces).map(async (ws) => {
+        const cred = await store.get(ws.app_id);
+        return {
+          app_id: ws.app_id,
+          name: ws.name,
+          auth_type: cred?.auth_type ?? "unknown",
+          default: ws.app_id === config.default
+        };
+      })
+    );
+    render(
+      workspaces,
+      opts,
+      () => {
+        if (workspaces.length === 0) {
+          return 'No workspaces configured. Run "intercom auth login" to get started.';
+        }
+        const rows = workspaces.map((ws) => ({
+          DEFAULT: ws.default ? "*" : "",
+          APP_ID: ws.app_id,
+          NAME: ws.name,
+          AUTH_TYPE: ws.auth_type
+        }));
+        return table({
+          columns: ["DEFAULT", "APP_ID", "NAME", "AUTH_TYPE"],
+          rows
+        });
+      },
+      workspaces
+    );
+  });
+}
+
+// src/commands/auth/switch.ts
+function registerSwitchCommand(auth) {
+  auth.command("switch <app_id>").description("Switch the default workspace").action(async (appId) => {
+    const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+    const config = await readConfig(configDir2);
+    if (!config.workspaces[appId]) {
+      const available = Object.keys(config.workspaces);
+      const hint = available.length > 0 ? ` Available: ${available.join(", ")}` : ' Run "intercom auth login" to add a workspace.';
+      throw new CLIError(`Workspace "${appId}" not found.${hint}`);
+    }
+    config.default = appId;
+    await writeConfig(config, configDir2);
+    const name = config.workspaces[appId].name;
+    console.log(`Switched to ${name} (${appId})`);
+  });
+}
+
 // src/commands/auth/index.ts
 function registerAuthCommand(program) {
   const auth = program.command("auth").description("Manage authentication credentials").addHelpText(
@@ -1202,7 +1378,9 @@ function registerAuthCommand(program) {
 Examples:
   intercom auth login --token <api-token>
   intercom auth status
-  intercom auth logout`
+  intercom auth logout
+
+Environment: Set INTERCOM_TOKEN to skip login entirely.`
   );
   registerLoginCommand(auth);
   registerBootstrapCommand(auth);
@@ -1210,6 +1388,8 @@ Examples:
   registerLogoutCommand(auth);
   registerSignupCommand(auth);
   registerVerifyEmailCommand(auth);
+  registerListCommand(auth);
+  registerSwitchCommand(auth);
 }
 
 // src/commands/me.ts
@@ -1245,7 +1425,7 @@ function htmlToText(html) {
 
 // src/commands/articles.ts
 function registerArticlesCommand(program) {
-  const articles = program.command("articles").description("Manage help center articles").addHelpText(
+  const articles = program.command("articles").description("Manage help center articles (list, get, create, update, delete)").addHelpText(
     "after",
     `
 Examples:
@@ -1255,7 +1435,13 @@ Examples:
   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() {
+  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").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom articles list --json
+  $ intercom articles list --all --jq '.[].title'`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     let result;
@@ -1312,7 +1498,16 @@ ${body}` : meta;
     "Typed field: bools, numbers, @file reads (repeatable)",
     (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() {
+  ).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom articles create -f title='Getting Started' -f body='<p>Hello</p>'
+  $ intercom articles create -F body=@article.html -f title='Guide'
+
+Common fields: title, body, author_id, state, parent_id, parent_type
+Use -F for typed values (numbers, booleans) and @file reads.`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const body = {
@@ -1377,7 +1572,7 @@ ${body}` : meta;
 
 // src/commands/contacts.ts
 function registerContactsCommand(program) {
-  const contacts = program.command("contacts").description("Manage contacts").addHelpText(
+  const contacts = program.command("contacts").description("Manage contacts (list, get, create, update, delete, search)").addHelpText(
     "after",
     `
 Examples:
@@ -1403,12 +1598,12 @@ Examples:
       result,
       opts,
       () => {
-        const rows = items.map((c) => ({
-          ID: String(c.id ?? ""),
-          EMAIL: String(c.email ?? ""),
-          NAME: String(c.name ?? ""),
-          ROLE: String(c.role ?? ""),
-          UPDATED: formatTimestamp(c.updated_at)
+        const rows = items.map((c2) => ({
+          ID: String(c2.id ?? ""),
+          EMAIL: String(c2.email ?? ""),
+          NAME: String(c2.name ?? ""),
+          ROLE: String(c2.role ?? ""),
+          UPDATED: formatTimestamp(c2.updated_at)
         }));
         return table({
           columns: ["ID", "EMAIL", "NAME", "ROLE", "UPDATED"],
@@ -1486,6 +1681,45 @@ Examples:
     const deleted = result;
     render(result, opts, () => `Deleted contact ${deleted.id ?? id}`);
   });
+  contacts.command("search").description("Search contacts (POST /contacts/search)").option(
+    "-f, --field <key=value>",
+    "String field (repeatable)",
+    (v, acc) => [...acc, v],
+    []
+  ).option(
+    "-F, --typed-field <key=value>",
+    "Typed field (repeatable)",
+    (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 body = {
+      ...parseTypedFields(opts.field ?? [], false),
+      ...parseTypedFields(opts.typedField ?? [], true)
+    };
+    const result = await client.post("/contacts/search", body);
+    const response = result;
+    const items = response.data ?? [];
+    render(
+      result,
+      opts,
+      () => {
+        const rows = items.map((c2) => ({
+          ID: String(c2.id ?? ""),
+          EMAIL: String(c2.email ?? ""),
+          NAME: String(c2.name ?? ""),
+          ROLE: String(c2.role ?? ""),
+          UPDATED: formatTimestamp(c2.updated_at)
+        }));
+        return table({
+          columns: ["ID", "EMAIL", "NAME", "ROLE", "UPDATED"],
+          rows
+        });
+      },
+      items
+    );
+  });
 }
 
 // src/commands/conversations.ts
@@ -1562,7 +1796,7 @@ function renderConversationStream(result) {
   return parts.join("\n");
 }
 function registerConversationsCommand(program) {
-  const conversations = program.command("conversations").description("Manage conversations").addHelpText(
+  const conversations = program.command("conversations").description("Manage conversations (list, get, reply, search)").addHelpText(
     "after",
     `
 Examples:
@@ -1591,12 +1825,12 @@ Examples:
       result,
       opts,
       () => {
-        const rows = items.map((c) => ({
-          ID: String(c.id ?? ""),
-          STATE: String(c.state ?? ""),
-          OPEN: String(c.open ?? ""),
-          CREATED: formatTimestamp(c.created_at),
-          UPDATED: formatTimestamp(c.updated_at)
+        const rows = items.map((c2) => ({
+          ID: String(c2.id ?? ""),
+          STATE: String(c2.state ?? ""),
+          OPEN: String(c2.open ?? ""),
+          CREATED: formatTimestamp(c2.created_at),
+          UPDATED: formatTimestamp(c2.updated_at)
         }));
         return table({
           columns: ["ID", "STATE", "OPEN", "CREATED", "UPDATED"],
@@ -1620,7 +1854,14 @@ Examples:
     "Field to set (repeatable)",
     (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(id) {
+  ).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom conversations reply 123 -f type=admin -f body='Thanks!'
+
+Required fields: body, type (admin or user). Also: admin_id, message_type.`
+  ).action(async function(id) {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const body = parseFieldArgs(opts.field ?? []);
@@ -1636,6 +1877,45 @@ Examples:
       })
     );
   });
+  conversations.command("search").description("Search conversations (POST /conversations/search)").option(
+    "-f, --field <key=value>",
+    "String field (repeatable)",
+    (v, acc) => [...acc, v],
+    []
+  ).option(
+    "-F, --typed-field <key=value>",
+    "Typed field (repeatable)",
+    (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 body = {
+      ...parseTypedFields(opts.field ?? [], false),
+      ...parseTypedFields(opts.typedField ?? [], true)
+    };
+    const result = await client.post("/conversations/search", body);
+    const response = result;
+    const items = response.conversations ?? [];
+    render(
+      result,
+      opts,
+      () => {
+        const rows = items.map((c2) => ({
+          ID: String(c2.id ?? ""),
+          STATE: String(c2.state ?? ""),
+          OPEN: String(c2.open ?? ""),
+          CREATED: formatTimestamp(c2.created_at),
+          UPDATED: formatTimestamp(c2.updated_at)
+        }));
+        return table({
+          columns: ["ID", "STATE", "OPEN", "CREATED", "UPDATED"],
+          rows
+        });
+      },
+      items
+    );
+  });
 }
 
 // src/commands/help-center.ts
@@ -1669,11 +1949,11 @@ Examples:
       result,
       opts,
       () => {
-        const rows = items.map((c) => ({
-          ID: String(c.id ?? ""),
-          NAME: String(c.name ?? ""),
-          DESCRIPTION: String(c.description ?? ""),
-          UPDATED: formatTimestamp(c.updated_at)
+        const rows = items.map((c2) => ({
+          ID: String(c2.id ?? ""),
+          NAME: String(c2.name ?? ""),
+          DESCRIPTION: String(c2.description ?? ""),
+          UPDATED: formatTimestamp(c2.updated_at)
         }));
         return table({
           columns: ["ID", "NAME", "DESCRIPTION", "UPDATED"],
@@ -1742,7 +2022,7 @@ export function IntercomWidget() {
 }`;
 }
 function registerMessengerCommand(program) {
-  const messenger = program.command("messenger").description("Manage Intercom Messenger settings").addHelpText(
+  const messenger = program.command("messenger").description("Manage Intercom Messenger settings (get, update, snippet)").addHelpText(
     "after",
     `
 Examples:
@@ -1750,7 +2030,13 @@ Examples:
   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() {
+  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").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom messenger get --json
+  $ intercom messenger get --jq '.alignment'`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const result = await client.get("/messenger", void 0, UNSTABLE_HEADERS);
@@ -1802,17 +2088,15 @@ Examples:
     "--format <format>",
     "Output format: html (default) or react",
     "html"
-  ).option("--verbose", "Show HTTP request/response details").action(async function() {
+  ).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 me = await client.get("/me");
     const app = me.app;
     const appId = String(app?.id_code ?? "");
-    if (opts.format === "react") {
-      console.log(generateReactSnippet(appId));
-    } else {
-      console.log(generateHtmlSnippet(appId));
-    }
+    const snippet = opts.format === "react" ? generateReactSnippet(appId) : generateHtmlSnippet(appId);
+    const format = opts.format ?? "html";
+    render({ format, snippet }, opts, () => snippet);
   });
 }
 
@@ -1941,11 +2225,11 @@ function registerGuidanceCommand(fin) {
       return table({ columns: ["ID", "NAME"], rows });
     }, items);
   });
-  guidance.command("get <id>").description("Download a guidance item by ID and print its YAML content").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+  guidance.command("get <id>").description("Download a guidance item by ID and print its YAML content").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 text = await client.getText(`/fin-sdk/guidance/${id}/download`);
-    console.log(text);
+    render({ format: "yaml", content: text }, opts, () => text);
   });
 }
 
@@ -2166,7 +2450,7 @@ async function emberRequest(session, path, options = {}) {
 }
 function extractCookies2(response) {
   const setCookies = typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : (response.headers.get("set-cookie") ?? "").split(/,(?=[^ ])/).filter(Boolean);
-  return setCookies.map((c) => c.split(";")[0]).join("; ");
+  return setCookies.map((c2) => c2.split(";")[0]).join("; ");
 }
 function mergeCookies2(existing, newCookies) {
   const map = /* @__PURE__ */ new Map();
@@ -2187,8 +2471,8 @@ function registerFinEnableCommand(fin) {
   ).requiredOption("--email <email>", "Admin email address").option("--password-stdin", "Read password from stdin (or set INTERCOM_PASSWORD)").option("--verify-email-url <url>", "Email verification URL (if email not yet verified)").option("--verbose", "Show detailed output").action(async function() {
     const opts = this.optsWithGlobals();
     const password = await resolvePassword({ passwordStdin: opts.passwordStdin });
-    const configDir = process.env.INTERCOM_CONFIG_DIR;
-    const config = await readConfig(configDir);
+    const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+    const config = await readConfig(configDir2);
     const appId = opts.workspace ?? config.default;
     if (!appId) {
       throw new CLIError(
@@ -2290,7 +2574,13 @@ Examples:
   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() {
+  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").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom fin manifest
+  $ intercom fin manifest --json`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const result = await client.get("/fin-sdk/manifest");
@@ -2333,7 +2623,7 @@ Examples:
 }
 
 // src/commands/setup.ts
-import { readdirSync, readFileSync as readFileSync3, statSync } from "fs";
+import { readdirSync, readFileSync as readFileSync4, statSync } from "fs";
 import { join as join3, basename as basename2 } from "path";
 function isGreenfield(opts) {
   return !!(opts.email && opts.name && (process.env.INTERCOM_PASSWORD || opts.passwordStdin));
@@ -2343,8 +2633,8 @@ function hasPartialGreenfieldFlags(opts) {
   return !!(opts.email && hasPassword && !opts.name);
 }
 async function hasExistingAuth() {
-  const configDir = process.env.INTERCOM_CONFIG_DIR;
-  const config = await readConfig(configDir);
+  const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+  const config = await readConfig(configDir2);
   return !!config.default;
 }
 function buildPlan(opts) {
@@ -2392,7 +2682,7 @@ function buildPlan(opts) {
     }
     if (mdFiles.length > 0) {
       const articleCommands = mdFiles.map((file) => {
-        const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.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({
@@ -2436,7 +2726,7 @@ async function runPostAuthSteps(client, opts, results, appId) {
   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
+    (c2) => String(c2.name ?? "") === helpCenterName
   );
   let collectionId;
   if (existingCollection) {
@@ -2459,8 +2749,8 @@ async function runPostAuthSteps(client, opts, results, appId) {
     let created = 0;
     let skipped = 0;
     for (const file of mdFiles) {
-      const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-      const body = readFileSync3(join3(opts.articlesFrom, file), "utf-8");
+      const title = basename2(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.toUpperCase());
+      const body = readFileSync4(join3(opts.articlesFrom, file), "utf-8");
       if (existingTitles.has(title)) {
         skipped++;
       } else {
@@ -2485,19 +2775,19 @@ async function runPostAuthSteps(client, opts, results, appId) {
   const articleCount = (await client.paginate("/articles")).length;
   if (articleCount === 0) {
     results.push(`\u26A0 No help center articles found!`);
-    console.log(results.join("\n"));
-    console.log("");
-    console.log("WARNING: Fin needs help center articles to answer questions.");
-    console.log("Without articles, Fin will have nothing to draw from and cannot help visitors.\n");
-    console.log("To add articles, either:");
-    console.log("  1. Re-run with: intercom setup --articles-from <directory-of-markdown-files>");
-    console.log('  2. Create articles manually: intercom articles create -f title="..." -f body="..." -F author_id=<id>');
-    console.log("");
-    console.log("Tip for AI agents: if no articles directory exists, consider creating one by");
-    console.log("  analyzing the project's source code, README, documentation, or any available");
-    console.log("  context about the product. Write markdown files covering key topics that");
-    console.log("  customers would ask about, then re-run setup with --articles-from.\n");
-    console.log("Skipping Fin enablement \u2014 enable Fin after adding articles with: intercom fin enable --email <email>");
+    console.error(results.join("\n"));
+    console.error("");
+    console.error("WARNING: Fin needs help center articles to answer questions.");
+    console.error("Without articles, Fin will have nothing to draw from and cannot help visitors.\n");
+    console.error("To add articles, either:");
+    console.error("  1. Re-run with: intercom setup --articles-from <directory-of-markdown-files>");
+    console.error('  2. Create articles manually: intercom articles create -f title="..." -f body="..." -F author_id=<id>');
+    console.error("");
+    console.error("Tip for AI agents: if no articles directory exists, consider creating one by");
+    console.error("  analyzing the project's source code, README, documentation, or any available");
+    console.error("  context about the product. Write markdown files covering key topics that");
+    console.error("  customers would ask about, then re-run setup with --articles-from.\n");
+    console.error("Skipping Fin enablement \u2014 enable Fin after adding articles with: intercom fin enable --email <email>");
     return;
   }
   results.push(`\u2713 ${articleCount} article(s) in help center`);
@@ -2521,8 +2811,8 @@ async function runPostAuthSteps(client, opts, results, appId) {
         results.push(`\u2713 Fin already opted in`);
       } else {
         results.push(`\u26A0 Fin opt-in failed (${optIn.status}) \u2014 enable manually with: intercom fin enable --email <email>`);
-        console.log(results.join("\n"));
-        console.log("Setup complete (Fin requires manual enablement).");
+        console.error(results.join("\n"));
+        console.error("Setup complete (Fin requires manual enablement).");
         return;
       }
       const profile = await emberRequest(
@@ -2553,7 +2843,7 @@ async function runPostAuthSteps(client, opts, results, appId) {
     }
   } else if (opts.enableFin !== false) {
     results.push(`\u26A0 Fin not enabled (--email required for Fin activation)`);
-    console.log("  Tip: Re-run with --email to enable Fin, or use: intercom fin enable --email <email>");
+    console.error("  Tip: Re-run with --email to enable Fin, or use: intercom fin enable --email <email>");
   }
   try {
     const manifest = await client.get("/fin-sdk/manifest");
@@ -2568,8 +2858,8 @@ async function runPostAuthSteps(client, opts, results, appId) {
       throw err;
     }
   }
-  console.log(results.join("\n"));
-  console.log("Setup complete!");
+  console.error(results.join("\n"));
+  console.error("Setup complete!");
 }
 function registerSetupCommand(program) {
   program.command("setup").description("Set up a complete Intercom installation").addHelpText(
@@ -2583,7 +2873,9 @@ Examples:
   INTERCOM_PASSWORD=*** intercom setup --email admin@acme.com --name "Admin" --company-name "Acme Inc"
 
   # Preview steps without executing
-  intercom setup --plan`
+  intercom setup --plan
+
+Flow: signup \u2192 auth \u2192 messenger \u2192 help center \u2192 articles \u2192 fin`
   ).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)) {
@@ -2694,10 +2986,10 @@ Then re-run setup without signup flags:
         );
       }
       results.push(`\u2713 Authentication token obtained`);
-      const configDir = process.env.INTERCOM_CONFIG_DIR;
-      const store = new CredentialStore(createDefaultBackend(configDir));
+      const configDir2 = process.env.INTERCOM_CONFIG_DIR;
+      const store = new CredentialStore(createDefaultBackend(configDir2));
       await store.set(workspace.id, { token, auth_type: "oauth", app_id: workspace.id });
-      await addWorkspace(configDir, { app_id: workspace.id, name: workspace.name });
+      await addWorkspace(configDir2, { app_id: workspace.id, name: workspace.name });
       const client2 = new IntercomClient({
         token,
         authType: "oauth",
@@ -2926,7 +3218,7 @@ function registerPricingCommand(program) {
     }
     const markdown = await response.text();
     if (opts.json) {
-      const { formatJson: formatJson2 } = await import("./json-TDEGGEUF.js");
+      const { formatJson: formatJson2 } = await import("./json-MMBOB7YU.js");
       console.log(formatJson2({ url: PRICING_URL, content: markdown }));
     } else {
       console.log(markdown);
@@ -2934,6 +3226,100 @@ function registerPricingCommand(program) {
   });
 }
 
+// src/commands/config.ts
+import { join as join4 } from "path";
+var SUPPORTED_KEYS = ["default_workspace", "timeout"];
+function configDir() {
+  return process.env.INTERCOM_CONFIG_DIR ?? defaultConfigDir();
+}
+function validateKey(key) {
+  if (!SUPPORTED_KEYS.includes(key)) {
+    throw new CLIError(
+      `Unknown config key "${key}". Supported keys: ${SUPPORTED_KEYS.join(", ")}`
+    );
+  }
+  return key;
+}
+async function getValue(key) {
+  const config = await readConfig(configDir());
+  switch (key) {
+    case "default_workspace":
+      return config.default;
+    case "timeout":
+      return config.timeout !== void 0 ? String(config.timeout) : void 0;
+  }
+}
+function resolveSource(key) {
+  switch (key) {
+    case "default_workspace":
+      return process.env.INTERCOM_WORKSPACE ? "INTERCOM_WORKSPACE" : "config";
+    case "timeout":
+      return "config";
+  }
+}
+async function setValue(key, value) {
+  const dir = configDir();
+  const config = await readConfig(dir);
+  switch (key) {
+    case "default_workspace":
+      config.default = value;
+      break;
+    case "timeout": {
+      const n = parseInt(value, 10);
+      if (isNaN(n) || n <= 0) {
+        throw new CLIError("timeout must be a positive integer (seconds)");
+      }
+      config.timeout = n;
+      break;
+    }
+  }
+  await writeConfig(config, dir);
+}
+function registerConfigCommand(program) {
+  const cmd = program.command("config").description("Manage CLI configuration");
+  cmd.command("list").description("List all configuration settings").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").action(async function() {
+    const opts = this.optsWithGlobals();
+    const config = await readConfig(configDir());
+    const entries = {};
+    for (const key of SUPPORTED_KEYS) {
+      const val = await getValue(key);
+      entries[key] = {
+        value: val ?? "",
+        source: val !== void 0 ? resolveSource(key) : ""
+      };
+    }
+    render(
+      entries,
+      opts,
+      () => table({
+        columns: ["KEY", "VALUE", "SOURCE"],
+        rows: SUPPORTED_KEYS.map((key) => ({
+          KEY: key,
+          VALUE: entries[key].value,
+          SOURCE: entries[key].source
+        }))
+      })
+    );
+  });
+  cmd.command("get <key>").description("Get a configuration value").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").action(async function(key) {
+    const opts = this.optsWithGlobals();
+    const validKey = validateKey(key);
+    const value = await getValue(validKey);
+    if (value === void 0) {
+      throw new CLIError(`Key "${key}" is not set`);
+    }
+    render({ key, value }, opts, () => value);
+  });
+  cmd.command("set <key> <value>").description("Set a configuration value").action(async function(key, value) {
+    const validKey = validateKey(key);
+    await setValue(validKey, value);
+    console.log(`Set ${key} = ${value}`);
+  });
+  cmd.command("path").description("Show configuration file path").action(async function() {
+    console.log(join4(configDir(), "config.json"));
+  });
+}
+
 // src/index.ts
 function detectBinaryName() {
   const argv1 = process.argv[1] ?? "";
@@ -2954,7 +3340,17 @@ function fullCommandName(cmd) {
 function createProgram() {
   const program = new Command();
   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");
+  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").option("--wide", "Show all columns with wider truncation").addHelpText(
+    "after",
+    `
+Quick start:
+  $ intercom auth login --token <your-api-token>
+  $ intercom me
+  $ intercom articles list --json
+  $ intercom setup --company-name "Acme" --articles-from ./docs
+
+Environment: Set INTERCOM_TOKEN to skip login entirely.`
+  );
   registerApiCommand(program);
   registerAuthCommand(program);
   registerMeCommand(program);
@@ -2967,6 +3363,7 @@ function createProgram() {
   registerSetupCommand(program);
   registerPricingCommand(program);
   registerCompletionCommand(program);
+  registerConfigCommand(program);
   program.hook("preAction", (thisCommand, actionCommand) => {
     const rootOpts = thisCommand.opts();
     if (rootOpts.agent && rootOpts.human) {