@intercom/cli 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 View it from the CLI with `intercom changelog`.
 
+## [0.9.0] - 2026-07-03
+
+### Added
+
+- `fin attributes upload <file>` creates or updates Fin custom attributes from a YAML file. Attributes were previously read-only (`list`). The file can be a list of attributes, a single attribute, or the full `type: attribute` / `attributes:` server shape — the CLI normalizes it and sets the routing type for you. Each attribute needs a dotted `name` (e.g. `user.order_status`) and a data `type` (`string`, `integer`, `decimal`, `float`, `boolean`, `list`, `date`, `object`, or `array`).
+- `fin procedures get <id> [output] --with-simulations` downloads a procedure's simulations alongside it. With the flag, `[output]` is a directory (default: current directory) and the CLI writes both `procedure.yaml` and `simulations.yaml`. Without it, `[output]` is a single file for the procedure YAML (previously `get` could only print to stdout).
+- `fin simulations upload <file>` re-uploads a simulation set (the `simulations.yaml` written by `fin procedures get --with-simulations`, or `fin simulations list` output), completing the export/edit/re-import round-trip for a procedure's tests.
+
 ## [0.8.3] - 2026-06-18
 
 ### Fixed

package/dist/index.js

@@ -2569,8 +2569,8 @@ Examples:
 import { writeFile as writeFile3 } from "fs/promises";
 
 // src/commands/fin/procedures.ts
-import { readFile as readFile2 } from "fs/promises";
-import { basename } from "path";
+import { readFile as readFile2, mkdir as mkdir2 } from "fs/promises";
+import { basename, join as join3 } from "path";
 import AdmZip from "adm-zip";
 function registerProceduresCommand(fin) {
   const procedures = fin.command("procedures").description("Manage Fin SDK procedures");
@@ -2591,7 +2591,21 @@ function registerProceduresCommand(fin) {
       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) {
+  procedures.command("get <id> [output]").description("Download a procedure by ID as YAML (writes to [output], or stdout)").option("--with-simulations", "Also download the procedure's simulations").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom fin procedures get proc-1                       # print YAML to stdout
+  $ intercom fin procedures get proc-1 procedure.yaml        # write YAML to a file
+  $ intercom fin procedures get proc-1 ./out --with-simulations
+      # writes ./out/procedure.yaml and ./out/simulations.yaml
+
+With --with-simulations, [output] is treated as a directory (default: current
+directory). Without it, [output] is a single file for the procedure YAML.
+
+Re-import the pieces with \`intercom fin procedures upload <procedure.yaml>\`
+and \`intercom fin simulations upload <simulations.yaml>\`.`
+  ).action(async function(id, output) {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const buffer = await client.getBuffer(`/fin-sdk/procedures/${id}/download`);
@@ -2600,7 +2614,28 @@ function registerProceduresCommand(fin) {
     if (!entry) {
       throw new Error("procedure.yaml not found in downloaded ZIP");
     }
-    console.log(zip.readAsText(entry));
+    const procedureYaml = zip.readAsText(entry);
+    let simulationsYaml;
+    if (opts.withSimulations) {
+      simulationsYaml = await client.getText(`/fin-sdk/procedures/${id}/simulations`);
+    }
+    if (opts.withSimulations) {
+      const dir = output ?? ".";
+      await mkdir2(dir, { recursive: true });
+      const procedurePath = join3(dir, "procedure.yaml");
+      const simulationsPath = join3(dir, "simulations.yaml");
+      await atomicWriteFile(procedurePath, procedureYaml, 420);
+      await atomicWriteFile(simulationsPath, simulationsYaml ?? "", 420);
+      console.error(`Wrote procedure ${id} to ${procedurePath}`);
+      console.error(`Wrote simulations to ${simulationsPath}`);
+      return;
+    }
+    if (output) {
+      await atomicWriteFile(output, procedureYaml, 420);
+      console.error(`Wrote procedure ${id} to ${output}`);
+    } else {
+      console.log(procedureYaml);
+    }
   });
   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();
@@ -2766,6 +2801,29 @@ Optional fields: state (live or paused, default: paused), audiences`
 }
 
 // src/commands/fin/attributes.ts
+import { readFile as readFile3 } from "fs/promises";
+import { basename as basename2 } from "path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var ATTRIBUTE_TYPE = "attribute";
+function buildAttributesUploadBody(raw) {
+  let parsed;
+  try {
+    parsed = parseYaml(raw);
+  } catch {
+    return raw;
+  }
+  if (Array.isArray(parsed)) {
+    return stringifyYaml({ type: ATTRIBUTE_TYPE, attributes: parsed });
+  }
+  if (parsed == null || typeof parsed !== "object") {
+    return raw;
+  }
+  const obj = parsed;
+  if (Array.isArray(obj.attributes)) {
+    return stringifyYaml({ ...obj, type: ATTRIBUTE_TYPE });
+  }
+  return stringifyYaml({ type: ATTRIBUTE_TYPE, attributes: [obj] });
+}
 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() {
@@ -2785,6 +2843,49 @@ function registerAttributesCommand(fin) {
       return table({ columns: ["NAME", "TYPE", "DESCRIPTION"], rows });
     }, items);
   });
+  attributes.command("upload <file>").description("Upload attributes from a YAML file (creates or updates)").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+The file holds one or more attributes. The CLI wraps them in the bulk shape the
+server expects and sets the routing type for you, so any of these work:
+
+  # a list of attributes
+  - name: user.order_status   # name must contain a dot
+    type: string              # data type: string, integer, decimal, float,
+    description: Order state   #   boolean, list, date, object, or array
+
+  # ...or a single attribute
+  name: company.tier
+  type: string
+
+  # ...or the full server shape
+  type: attribute
+  attributes:
+    - name: user.order_status
+      type: string
+
+Examples:
+  $ intercom fin attributes upload ./attributes.yaml
+  $ intercom fin attributes upload ./attributes.yaml --json`
+  ).action(async function(filePath) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const fileContent = await readFile3(filePath, "utf8");
+    const yamlBody = buildAttributesUploadBody(fileContent);
+    const formData = new FormData();
+    const blob = new Blob([yamlBody], { type: "application/x-yaml" });
+    formData.append("file_data", blob, basename2(filePath));
+    const result = await client.postFormData("/fin-sdk/upload", formData);
+    render(
+      result,
+      opts,
+      () => detail({
+        "ID": result.id != null ? String(result.id) : void 0,
+        "Type": result.type != null ? String(result.type) : void 0,
+        "Message": result.message != null ? String(result.message) : void 0
+      })
+    );
+  });
 }
 
 // src/commands/fin/audiences.ts
@@ -2809,16 +2910,16 @@ function registerAudiencesCommand(fin) {
 }
 
 // src/commands/fin/workflows.ts
-import { readFile as readFile3 } from "fs/promises";
-import { basename as basename2 } from "path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { readFile as readFile4 } from "fs/promises";
+import { basename as basename3 } from "path";
+import { parse as parseYaml2, stringify as stringifyYaml2 } from "yaml";
 var STATE_LIVE = "live";
 var STATE_PAUSED = "paused";
 var WORKFLOW_TYPE = "workflow";
 function ensureWorkflowType(raw) {
   let parsed;
   try {
-    parsed = parseYaml(raw);
+    parsed = parseYaml2(raw);
   } catch {
     return raw;
   }
@@ -2830,7 +2931,7 @@ function ensureWorkflowType(raw) {
     return raw;
   }
   obj.type = WORKFLOW_TYPE;
-  return stringifyYaml(obj);
+  return stringifyYaml2(obj);
 }
 function registerWorkflowsCommand(fin) {
   const workflows = fin.command("workflows").description("Manage Fin SDK workflows");
@@ -2867,7 +2968,7 @@ The YAML it prints is ready to edit and re-upload with
     const client = await resolveClient(opts);
     const text = await client.getText(`/fin-sdk/workflows/${id}`);
     if (opts.json || opts.jq || opts.agent) {
-      const parsed = parseYaml(text);
+      const parsed = parseYaml2(text);
       render(parsed, opts, () => formatJson(parsed));
       return;
     }
@@ -2892,11 +2993,11 @@ The YAML file's id field determines whether this creates or updates:
   ).action(async function(filePath) {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
-    const fileContent = await readFile3(filePath, "utf8");
+    const fileContent = await readFile4(filePath, "utf8");
     const yamlBody = ensureWorkflowType(fileContent);
     const formData = new FormData();
     const blob = new Blob([yamlBody], { type: "application/x-yaml" });
-    formData.append("file_data", blob, basename2(filePath));
+    formData.append("file_data", blob, basename3(filePath));
     const result = await client.postFormData("/fin-sdk/upload", formData);
     render(
       result,
@@ -2925,13 +3026,13 @@ overwritten (the server does not expose a concurrency token).`
     const text = await client.getText(`/fin-sdk/workflows/${id}`);
     let parsed;
     try {
-      parsed = parseYaml(text);
+      parsed = parseYaml2(text);
     } catch (err) {
       throw new Error(`server returned unparseable YAML for workflow ${id}: ${err.message}`);
     }
     parsed.type = WORKFLOW_TYPE;
     parsed.state = STATE_LIVE;
-    const yamlBody = stringifyYaml(parsed);
+    const yamlBody = stringifyYaml2(parsed);
     const formData = new FormData();
     const blob = new Blob([yamlBody], { type: "application/x-yaml" });
     formData.append("file_data", blob, `workflow-${id}.yaml`);
@@ -2962,13 +3063,13 @@ overwritten (the server does not expose a concurrency token).`
     const text = await client.getText(`/fin-sdk/workflows/${id}`);
     let parsed;
     try {
-      parsed = parseYaml(text);
+      parsed = parseYaml2(text);
     } catch (err) {
       throw new Error(`server returned unparseable YAML for workflow ${id}: ${err.message}`);
     }
     parsed.type = WORKFLOW_TYPE;
     parsed.state = STATE_PAUSED;
-    const yamlBody = stringifyYaml(parsed);
+    const yamlBody = stringifyYaml2(parsed);
     const formData = new FormData();
     const blob = new Blob([yamlBody], { type: "application/x-yaml" });
     formData.append("file_data", blob, `workflow-${id}.yaml`);
@@ -2986,6 +3087,27 @@ overwritten (the server does not expose a concurrency token).`
 }
 
 // src/commands/fin/simulations.ts
+import { readFile as readFile5 } from "fs/promises";
+import { basename as basename4 } from "path";
+import { parse as parseYaml3, stringify as stringifyYaml3 } from "yaml";
+var SIMULATION_SET_TYPE = "simulation_set";
+function ensureSimulationSetType(raw) {
+  let parsed;
+  try {
+    parsed = parseYaml3(raw);
+  } catch {
+    return raw;
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return raw;
+  }
+  const obj = parsed;
+  if (obj.type != null && obj.type !== "") {
+    return raw;
+  }
+  obj.type = SIMULATION_SET_TYPE;
+  return stringifyYaml3(obj);
+}
 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) {
@@ -2994,6 +3116,36 @@ function registerSimulationsCommand(fin) {
     const text = await client.getText(`/fin-sdk/procedures/${procedureId}/simulations`);
     console.log(text);
   });
+  simulations.command("upload <file>").description("Upload a simulation set YAML file for its procedure").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+The file is a simulation set carrying its own procedure_id, as produced by
+\`intercom fin procedures get <id> ./out --with-simulations\` (writes
+./out/simulations.yaml) or \`intercom fin simulations list <procedure_id>\`.
+This completes the export/edit/re-import round-trip for a procedure's tests.
+
+Example:
+  $ intercom fin simulations upload ./out/simulations.yaml`
+  ).action(async function(filePath) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const fileContent = await readFile5(filePath, "utf8");
+    const yamlBody = ensureSimulationSetType(fileContent);
+    const formData = new FormData();
+    const blob = new Blob([yamlBody], { type: "application/x-yaml" });
+    formData.append("file_data", blob, basename4(filePath));
+    const result = await client.postFormData("/fin-sdk/upload", formData);
+    render(
+      result,
+      opts,
+      () => detail({
+        "ID": result.id != null ? String(result.id) : void 0,
+        "Procedure ID": result.procedure_id != null ? String(result.procedure_id) : void 0,
+        "Type": result.type != null ? String(result.type) : void 0,
+        "Message": result.message != null ? String(result.message) : void 0
+      })
+    );
+  });
   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);
@@ -3223,8 +3375,8 @@ Fin is live on workspace ${appId}`);
 }
 
 // src/commands/fin/monitors.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import { join as join3, relative, dirname } from "path";
+import { mkdir as mkdir3, writeFile as writeFile2 } from "fs/promises";
+import { join as join4, relative, dirname } from "path";
 import { stringify } from "yaml";
 async function resolveMonitorId(client, nameOrId) {
   if (/^\d+$/.test(nameOrId)) {
@@ -3305,14 +3457,14 @@ Examples:
       );
       return;
     }
-    const outputPath = opts.output ?? join3(
+    const outputPath = opts.output ?? join4(
       process.cwd(),
       "src",
       "qa",
       "bulk-actions",
       "flagged-conversations.yaml"
     );
-    await mkdir2(dirname(outputPath), { recursive: true });
+    await mkdir3(dirname(outputPath), { recursive: true });
     await writeFile2(outputPath, buildWorkingSetYaml(result, since), "utf-8");
     const relPath = relative(process.cwd(), outputPath);
     console.log(
@@ -3330,8 +3482,8 @@ Examples:
 }
 
 // src/commands/fin/conversation.ts
-import { readFile as readFile4 } from "fs/promises";
-import { join as join4 } from "path";
+import { readFile as readFile6 } from "fs/promises";
+import { join as join5 } from "path";
 import { parse } from "yaml";
 var PLACEHOLDER_MESSAGE = "Your message here \u2014 this will be sent to all conversations listed below.";
 function validateWorkingSet(ws) {
@@ -3381,7 +3533,7 @@ function registerConversationCommand(fin) {
   ).option(
     "--file <path>",
     "Path to the working set YAML file",
-    join4(process.cwd(), "src", "qa", "bulk-actions", "flagged-conversations.yaml")
+    join5(process.cwd(), "src", "qa", "bulk-actions", "flagged-conversations.yaml")
   ).option("--dry-run", "Preview actions without sending").option("--yes", "Skip confirmation prompt (required in TTY mode)").option(
     "--json",
     "Output result as JSON"
@@ -3395,7 +3547,7 @@ Examples:
   $ fin conversation bulk-send --json`
   ).action(async function() {
     const opts = this.optsWithGlobals();
-    const filePath = opts.file ?? join4(
+    const filePath = opts.file ?? join5(
       process.cwd(),
       "src",
       "qa",
@@ -3404,7 +3556,7 @@ Examples:
     );
     let raw;
     try {
-      raw = await readFile4(filePath, "utf-8");
+      raw = await readFile6(filePath, "utf-8");
     } catch (err) {
       const e = err;
       if (e.code === "ENOENT") {
@@ -3565,7 +3717,7 @@ Examples:
 
 // src/commands/setup.ts
 import { readdirSync, readFileSync as readFileSync4, statSync } from "fs";
-import { join as join5, basename as basename3 } from "path";
+import { join as join6, basename as basename5 } from "path";
 function isGreenfield(opts) {
   return !!(opts.email && opts.name && (process.env.INTERCOM_PASSWORD || opts.passwordStdin));
 }
@@ -3623,8 +3775,8 @@ function buildPlan(opts) {
     }
     if (mdFiles.length > 0) {
       const articleCommands = mdFiles.map((file) => {
-        const title = basename3(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.toUpperCase());
-        return `intercom articles create -f title="${title}" -F body=@${join5(opts.articlesFrom, file)} -f author_id=$(intercom me --json | jq -r .id)`;
+        const title = basename5(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.toUpperCase());
+        return `intercom articles create -f title="${title}" -F body=@${join6(opts.articlesFrom, file)} -f author_id=$(intercom me --json | jq -r .id)`;
       });
       steps.push({
         step: stepNum++,
@@ -3690,8 +3842,8 @@ async function runPostAuthSteps(client, opts, results, appId) {
     let created = 0;
     let skipped = 0;
     for (const file of mdFiles) {
-      const title = basename3(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.toUpperCase());
-      const body = readFileSync4(join5(opts.articlesFrom, file), "utf-8");
+      const title = basename5(file, ".md").replace(/-/g, " ").replace(/\b\w/g, (c2) => c2.toUpperCase());
+      const body = readFileSync4(join6(opts.articlesFrom, file), "utf-8");
       if (existingTitles.has(title)) {
         skipped++;
       } else {
@@ -4168,7 +4320,7 @@ function registerPricingCommand(program) {
 }
 
 // src/commands/config.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 var SUPPORTED_KEYS = ["default_workspace", "timeout"];
 function configDir() {
   return process.env.INTERCOM_CONFIG_DIR ?? defaultConfigDir();
@@ -4257,7 +4409,7 @@ function registerConfigCommand(program) {
     console.log(`Set ${key} = ${value}`);
   });
   cmd.command("path").description("Show configuration file path").action(async function() {
-    console.log(join6(configDir(), "config.json"));
+    console.log(join7(configDir(), "config.json"));
   });
 }
 

package/package.json

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