@intercom/cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 View it from the CLI with `intercom changelog`.
 
+## [0.12.0] - 2026-08-26
+
+### Added
+
+- `intercom internal-articles` manages the private knowledge Fin reads: `list`, `get`, `create`, `update` and `delete`. Previously internal articles could only be reached through raw `intercom api` calls. Pass `--unstable` to include each article's `folder_id` in the output.
+- `intercom internal-articles folders list` and `folders get <id>` read the internal article folder tree. Walk `parent_folder_id` to rebuild the hierarchy and match each article to a folder by its `folder_id`. These always send `Intercom-Version: Unstable`, because the folders API is not generally available yet.
+- `intercom internal-articles folders articles <folder-id>` lists the articles in a folder and every folder below it.
+
+## [0.11.0] - 2026-08-17
+
+### Added
+
+- `fin workflows versions <id>` lists a workflow's server-side version history, showing which version is live, which is draft, and who saved it. `fin workflows get <id> --version <version_id>` downloads any of those versions as re-uploadable YAML, so a local file can be diffed against what Fin is actually running.
+
 ## [0.10.0] - 2026-08-17
 
 ### Added

package/dist/index.js

@@ -327,9 +327,9 @@ ${await value.text()}`);
   async postFormData(path, formData) {
     return this.request("POST", path, formData);
   }
-  async paginate(path, params, dataKey = "data") {
+  async paginate(path, params, dataKey = "data", headers) {
     const allData = [];
-    const firstResponse = await this.get(path, { ...params });
+    const firstResponse = await this.get(path, { ...params }, headers);
     const firstData = firstResponse[dataKey];
     if (firstData) allData.push(...firstData);
     const pages = firstResponse.pages;
@@ -337,10 +337,11 @@ ${await value.text()}`);
     if (startingAfter) {
       let cursor = startingAfter;
       while (cursor) {
-        const response = await this.get(path, {
-          ...params,
-          starting_after: cursor
-        });
+        const response = await this.get(
+          path,
+          { ...params, starting_after: cursor },
+          headers
+        );
         const data = response[dataKey];
         if (data) allData.push(...data);
         const p = response.pages;
@@ -350,7 +351,11 @@ ${await value.text()}`);
     }
     const totalPages = pages?.total_pages ?? 1;
     for (let page = 2; page <= totalPages; page++) {
-      const response = await this.get(path, { ...params, page: String(page) });
+      const response = await this.get(
+        path,
+        { ...params, page: String(page) },
+        headers
+      );
       const data = response[dataKey];
       if (data) allData.push(...data);
     }
@@ -1790,6 +1795,356 @@ Use -F for typed values (numbers, booleans) and @file reads.`
   });
 }
 
+// src/commands/internal-articles.ts
+var UNSTABLE_HEADERS = { "Intercom-Version": "Unstable" };
+var BODY_KEY = "internal_article";
+var INTEGER_FIELDS = ["owner_id", "author_id", "folder_id"];
+function stripBody2(items) {
+  return items.map(({ body: _body, json_blocks: _blocks, ...rest }) => rest);
+}
+function headersFor(opts) {
+  return opts.unstable ? UNSTABLE_HEADERS : void 0;
+}
+function buildBody(opts) {
+  const attrs = {
+    ...parseFieldArgs(opts.field ?? []),
+    ...parseTypedFields(opts.typedField ?? [], true)
+  };
+  for (const key of INTEGER_FIELDS) {
+    if (typeof attrs[key] === "string") {
+      const parsed = parseInt(attrs[key], 10);
+      if (!isNaN(parsed)) attrs[key] = parsed;
+    }
+  }
+  return { [BODY_KEY]: attrs };
+}
+function articleRows(items) {
+  return items.map((a) => ({
+    ID: String(a.id ?? ""),
+    TITLE: String(a.title ?? ""),
+    FOLDER: a.folder_id != null ? String(a.folder_id) : "",
+    LOCALE: String(a.locale ?? ""),
+    UPDATED: formatTimestamp(a.updated_at)
+  }));
+}
+var ARTICLE_COLUMNS = ["ID", "TITLE", "FOLDER", "LOCALE", "UPDATED"];
+function articleDetail(result) {
+  const meta = detail({
+    ID: String(result.id ?? ""),
+    Title: String(result.title ?? ""),
+    Locale: String(result.locale ?? ""),
+    "Folder ID": result.folder_id != null ? String(result.folder_id) : void 0,
+    "Owner ID": result.owner_id != null ? String(result.owner_id) : void 0,
+    "Author ID": result.author_id != null ? String(result.author_id) : void 0,
+    Updated: formatTimestamp(result.updated_at),
+    Created: formatTimestamp(result.created_at)
+  });
+  const body = typeof result.body === "string" ? htmlToText(result.body) : "";
+  return body ? `${meta}
+
+${body}` : meta;
+}
+function addCommonOptions(cmd) {
+  return cmd.option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details");
+}
+function addFieldOptions(cmd) {
+  return cmd.option(
+    "-f, --field <key=value>",
+    "Field to set (repeatable)",
+    (v, acc) => [...acc, v],
+    []
+  ).option(
+    "-F, --typed-field <key=value>",
+    "Typed field: bools, numbers, @file reads (repeatable)",
+    (v, acc) => [...acc, v],
+    []
+  );
+}
+function registerInternalArticlesCommand(program) {
+  const internalArticles = program.command("internal-articles").description(
+    "Manage internal articles (list, get, create, update, delete, folders)"
+  ).addHelpText(
+    "after",
+    `
+Internal articles are the private knowledge Fin reads but end users never see.
+They are separate from "intercom articles", which manages public help center content.
+
+Examples:
+  intercom internal-articles list
+  intercom internal-articles list --unstable        # include folder_id
+  intercom internal-articles get 123
+  intercom internal-articles create -f title='Refunds' -f owner_id=1 -f author_id=1 -F body_markdown=@refunds.md
+  intercom internal-articles update 123 -f title='Refunds (2026)'
+  intercom internal-articles delete 123
+  intercom internal-articles folders list           # folder hierarchy`
+  );
+  addCommonOptions(
+    internalArticles.command("list").description("List internal articles").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").option(
+      "--body",
+      "Include the body and json_blocks fields (omitted by default to keep output small)"
+    ).option(
+      "--unstable",
+      "Send Intercom-Version: Unstable, which adds folder_id to each article"
+    )
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom internal-articles list --json
+  $ intercom internal-articles list --all --jq '.[].title'
+  $ intercom internal-articles list --unstable --json  # include folder_id
+  $ intercom internal-articles list --body --json      # include full body`
+  ).action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const headers = headersFor(opts);
+    let result;
+    if (opts.all) {
+      const allItems = await client.paginate(
+        "/internal_articles",
+        { per_page: "50" },
+        "data",
+        headers
+      );
+      result = {
+        type: "list",
+        data: opts.body ? allItems : stripBody2(allItems)
+      };
+    } else {
+      const raw = await client.get(
+        "/internal_articles",
+        { per_page: opts.limit ?? "25" },
+        headers
+      );
+      if (!opts.body && Array.isArray(raw.data)) {
+        raw.data = stripBody2(raw.data);
+      }
+      result = raw;
+    }
+    const items = result.data ?? [];
+    render(
+      result,
+      opts,
+      () => table({ columns: ARTICLE_COLUMNS, rows: articleRows(items) }),
+      items
+    );
+  });
+  addCommonOptions(
+    internalArticles.command("get <id>").description("Get an internal article by ID").option(
+      "--unstable",
+      "Send Intercom-Version: Unstable, which adds folder_id to the article"
+    )
+  ).action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(
+      `/internal_articles/${id}`,
+      void 0,
+      headersFor(opts)
+    );
+    render(result, opts, () => articleDetail(result));
+  });
+  addCommonOptions(
+    addFieldOptions(
+      internalArticles.command("create").description("Create an internal article").option(
+        "--unstable",
+        "Send Intercom-Version: Unstable, needed to set folder_id"
+      )
+    )
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom internal-articles create -f title='Refund policy' -f owner_id=1 -f author_id=1 -F body_markdown=@refunds.md
+  $ intercom internal-articles create -f title='Escalations' -f owner_id=1 -f author_id=1 -f folder_id=7 --unstable
+
+Required fields: title, owner_id, author_id
+Content: pass body (HTML) or body_markdown (Markdown), not both.
+Use -F for typed values (numbers, booleans) and @file reads.`
+  ).action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.post(
+      "/internal_articles",
+      buildBody(opts),
+      headersFor(opts)
+    );
+    render(
+      result,
+      opts,
+      () => articleDetail(result)
+    );
+  });
+  addCommonOptions(
+    addFieldOptions(
+      internalArticles.command("update <id>").description("Update an internal article").option(
+        "--unstable",
+        "Send Intercom-Version: Unstable, needed to set folder_id"
+      )
+    )
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom internal-articles update 123 -f title='Refund policy (2026)'
+  $ intercom internal-articles update 123 -F body_markdown=@refunds.md
+  $ intercom internal-articles update 123 -f folder_id=7 --unstable`
+  ).action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.put(
+      `/internal_articles/${id}`,
+      buildBody(opts),
+      headersFor(opts)
+    );
+    render(
+      result,
+      opts,
+      () => articleDetail(result)
+    );
+  });
+  addCommonOptions(
+    internalArticles.command("delete <id>").description("Delete an internal article")
+  ).action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.delete(`/internal_articles/${id}`);
+    const deleted = result;
+    render(result, opts, () => `Deleted internal article ${deleted.id ?? id}`);
+  });
+  const folders = internalArticles.command("folders").description("List and inspect internal article folders").addHelpText(
+    "after",
+    `
+Folders are served only on the Unstable API version until the folders API is
+released, so these subcommands always send Intercom-Version: Unstable.
+
+Reconstruct the hierarchy by walking parent_folder_id, then match articles to
+folders with the folder_id from "internal-articles list --unstable".
+
+Examples:
+  intercom internal-articles folders list
+  intercom internal-articles folders list --parent-folder-id 7
+  intercom internal-articles folders get 7
+  intercom internal-articles folders articles 7`
+  );
+  addCommonOptions(
+    folders.command("list").description("List internal article folders").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").option(
+      "--parent-folder-id <id>",
+      "Only return folders directly inside this folder"
+    )
+  ).action(async function() {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const params = {};
+    if (opts.parentFolderId) params.parent_folder_id = opts.parentFolderId;
+    let result;
+    if (opts.all) {
+      const allItems = await client.paginate(
+        "/folders",
+        { ...params, per_page: "50" },
+        "data",
+        UNSTABLE_HEADERS
+      );
+      result = { type: "list", data: allItems };
+    } else {
+      result = await client.get(
+        "/folders",
+        { ...params, per_page: opts.limit ?? "25" },
+        UNSTABLE_HEADERS
+      );
+    }
+    const items = result.data ?? [];
+    render(
+      result,
+      opts,
+      () => {
+        if (items.length === 0) return "No folders found.";
+        const rows = items.map((f) => ({
+          ID: String(f.id ?? ""),
+          NAME: String(f.name ?? ""),
+          PARENT: f.parent_folder_id != null ? String(f.parent_folder_id) : "",
+          ITEMS: f.content_count != null ? String(f.content_count) : ""
+        }));
+        return table({ columns: ["ID", "NAME", "PARENT", "ITEMS"], rows });
+      },
+      items
+    );
+  });
+  addCommonOptions(
+    folders.command("get <id>").description("Get an internal article folder by ID")
+  ).action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(`/folders/${id}`, void 0, UNSTABLE_HEADERS);
+    render(
+      result,
+      opts,
+      () => detail({
+        ID: String(result.id ?? ""),
+        Name: String(result.name ?? ""),
+        Description: result.description != null ? String(result.description) : void 0,
+        Emoji: result.emoji != null ? String(result.emoji) : void 0,
+        "Parent folder ID": result.parent_folder_id != null ? String(result.parent_folder_id) : void 0,
+        Items: result.content_count != null ? String(result.content_count) : void 0,
+        Updated: formatTimestamp(result.updated_at),
+        Created: formatTimestamp(result.created_at)
+      })
+    );
+  });
+  addCommonOptions(
+    folders.command("articles <folder-id>").description("List the articles in a folder and everything below it").option("--limit <n>", "Max results to return", "25").option("--all", "Auto-paginate all pages").option(
+      "--body",
+      "Include the body and json_blocks fields (omitted by default to keep output small)"
+    )
+  ).addHelpText(
+    "after",
+    `
+This walks the folder tree, so it returns the articles in every descendant
+folder too, not just the ones directly inside.
+
+Examples:
+  $ intercom internal-articles folders articles 7
+  $ intercom internal-articles folders articles 7 --all --jq '.[].title'`
+  ).action(async function(folderId) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const params = { folder_id: folderId };
+    let result;
+    if (opts.all) {
+      const allItems = await client.paginate(
+        "/internal_articles/search",
+        { ...params, per_page: "50" },
+        "internal_articles",
+        UNSTABLE_HEADERS
+      );
+      result = {
+        type: "list",
+        internal_articles: opts.body ? allItems : stripBody2(allItems)
+      };
+    } else {
+      const raw = await client.get(
+        "/internal_articles/search",
+        { ...params, per_page: opts.limit ?? "25" },
+        UNSTABLE_HEADERS
+      );
+      if (!opts.body && Array.isArray(raw.internal_articles)) {
+        raw.internal_articles = stripBody2(raw.internal_articles);
+      }
+      result = raw;
+    }
+    const items = result.internal_articles ?? [];
+    render(
+      result,
+      opts,
+      () => {
+        if (items.length === 0) return "No internal articles found.";
+        return table({ columns: ARTICLE_COLUMNS, rows: articleRows(items) });
+      },
+      items
+    );
+  });
+}
+
 // src/commands/contacts.ts
 function registerContactsCommand(program) {
   const contacts = program.command("contacts").description("Manage contacts (list, get, create, update, delete, search)").addHelpText(
@@ -2258,7 +2613,7 @@ Examples:
 }
 
 // src/commands/messenger.ts
-var UNSTABLE_HEADERS = { "Intercom-Version": "Unstable" };
+var UNSTABLE_HEADERS2 = { "Intercom-Version": "Unstable" };
 var WIDGET_LOADER = (appId) => `(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/${appId}';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};if(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();`;
 function generateHtmlJwtSnippet(appId) {
   return `<!--
@@ -2491,7 +2846,7 @@ Examples:
   ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
-    const result = await client.get("/messenger", void 0, UNSTABLE_HEADERS);
+    const result = await client.get("/messenger", void 0, UNSTABLE_HEADERS2);
     const r = result;
     render(
       result,
@@ -2518,7 +2873,7 @@ Examples:
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const body = parseFieldArgs(opts.field ?? []);
-    const result = await client.put("/messenger", body, UNSTABLE_HEADERS);
+    const result = await client.put("/messenger", body, UNSTABLE_HEADERS2);
     const r = result;
     render(
       result,
@@ -3183,20 +3538,26 @@ function registerWorkflowsCommand(fin) {
       return table({ columns: ["ID", "TITLE", "STATE", "TRIGGER"], rows });
     }, items);
   });
-  workflows.command("get <id> [output]").description("Get a workflow by ID as YAML (writes to [output] file, or stdout)").option("--json", "Output as parsed JSON instead of YAML").option("--jq <expr>", "Filter parsed-JSON output with a jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+  workflows.command("get <id> [output]").description("Get a workflow by ID as YAML (writes to [output] file, or stdout)").option("--json", "Output as parsed JSON instead of YAML").option("--jq <expr>", "Filter parsed-JSON output with a jq expression").option("--version <version_id>", "Download a historical version instead of the current one").option("--verbose", "Show HTTP request/response details").addHelpText(
     "after",
     `
 Examples:
   $ intercom fin workflows get 42 workflow.yaml     # write YAML to a file
   $ intercom fin workflows get 42 > workflow.yaml   # or redirect stdout
   $ intercom fin workflows get 42 --json | jq .state
+  $ intercom fin workflows versions 42              # find a version ID
+  $ intercom fin workflows get 42 --version 4821    # print that version's YAML
 
 The YAML it prints is ready to edit and re-upload with
-\`intercom fin workflows upload\`.`
+\`intercom fin workflows upload\`.
+
+--version downloads the re-uploadable YAML of a historical version, so you can
+diff a local file against what is live (\`intercom fin workflows versions <id>\`
+shows which version that is).`
   ).action(async function(id, output) {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
-    const text = await client.getText(`/fin-sdk/workflows/${id}`);
+    const text = opts.version ? await getVersionYaml2(client, id, opts.version) : await client.getText(`/fin-sdk/workflows/${id}`);
     if (opts.json || opts.jq || opts.agent) {
       const parsed = parseYaml3(text);
       render(parsed, opts, () => formatJson(parsed));
@@ -3314,6 +3675,45 @@ overwritten (the server does not expose a concurrency token).`
       })
     );
   });
+  workflows.command("versions <id>").description("List a workflow's server-side version history (which one is live)").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 workflows versions 42
+  $ intercom fin workflows versions 42 --jq '.entity_version_id'
+
+STATUS is the server's own vocabulary: live is what Fin is running now, draft is
+unpublished, previously_live is superseded. Download any of them with
+\`intercom fin workflows get <id> --version <VERSION>\`.`
+  ).action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(`/fin-sdk/workflows/${id}/versions`);
+    const items = result.versions ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No versions found.";
+      }
+      const rows = items.map((v) => ({
+        VERSION: String(v.entity_version_id ?? ""),
+        STATUS: String(v.status ?? ""),
+        CREATED: String(v.created_at ?? ""),
+        AUTHOR: String(v.author?.name ?? ""),
+        NOTE: String(v.note ?? "")
+      }));
+      return table({ columns: ["VERSION", "STATUS", "CREATED", "AUTHOR", "NOTE"], rows });
+    }, items);
+  });
+}
+async function getVersionYaml2(client, id, versionId) {
+  const result = await client.get(
+    `/fin-sdk/workflows/${id}/versions/${versionId}`
+  );
+  const content = result.content;
+  if (content == null) {
+    throw new CLIError(`Workflow version ${versionId} returned no content`);
+  }
+  return typeof content === "string" ? content : stringifyYaml3(content);
 }
 
 // src/commands/fin/simulations.ts
@@ -4776,6 +5176,7 @@ Environment: Set INTERCOM_TOKEN to skip login entirely.`;
   registerAuthCommand(program);
   registerMeCommand(program);
   registerArticlesCommand(program);
+  registerInternalArticlesCommand(program);
   registerContactsCommand(program);
   registerConversationsCommand(program);
   registerHelpCenterCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intercom/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "CLI tool for managing Intercom workspaces",
   "type": "module",
   "packageManager": "pnpm@10.23.0",