@aifabrix/builder 2.45.5 → 2.47.0

package/lib/commands/governance-upload-external.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview governance upload — push integration/<systemKey>/scenarios/*.yaml (424.0).
+ */
+
+'use strict';
+
+const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+const { resolveGovernanceIntegrationContext } = require('./governance-cli-shared');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceUploadForExternalSystem(systemKey, options = {}) {
+  const { resolvedKey, authConfig, dataplaneUrl } = await resolveGovernanceIntegrationContext(
+    systemKey,
+    options
+  );
+  const uploaded = await uploadGovernanceScenarioPacks(
+    resolvedKey,
+    dataplaneUrl,
+    authConfig,
+    { silent: options.json === true }
+  );
+  return {
+    systemKey: resolvedKey,
+    command: 'governance upload',
+    uploaded
+  };
+}
+
+module.exports = {
+  runGovernanceUploadForExternalSystem
+};

package/lib/commands/governance-verify-external.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview governance verify — run persisted packs (424.0).
+ */
+
+'use strict';
+
+const { runVerifyGovernanceFromDbPacks } = require('./verify-governance-db');
+const {
+  sumEnforcementScenarios,
+  aggregateCoverage,
+  buildPackOverrideResult
+} = require('./verify-governance-result-builders');
+const { VERDICT, verdictFromPassed } = require('../lifecycle/product-model');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceVerifyForExternalSystem(systemKey, options = {}) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'governance verify applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+
+  if (options.pack) {
+    const { runTestGovernanceForExternalSystem } = require('./test-governance-external');
+    const runPayload = await runTestGovernanceForExternalSystem(systemKey, options);
+    return buildPackOverrideResult(systemKey, runPayload, 'governance verify');
+  }
+
+  const { resolvedKey, datasourceRows } = await runVerifyGovernanceFromDbPacks(systemKey, options);
+  if (datasourceRows.length === 0) {
+    return {
+      systemKey: resolvedKey,
+      command: 'governance verify',
+      verdict: VERDICT.FAILED,
+      policyCoveragePercent: 0,
+      dimensionCoveragePercent: 0,
+      enforcementScenarios: { passed: 0, total: 0 },
+      datasourceRows: []
+    };
+  }
+
+  const allVerified = datasourceRows.every(r => r.verdict === VERDICT.VERIFIED);
+  const coverage = aggregateCoverage(datasourceRows);
+  return {
+    systemKey: resolvedKey,
+    command: 'governance verify',
+    verdict: verdictFromPassed(allVerified),
+    policyCoveragePercent: coverage.policy ?? (allVerified ? 100 : 0),
+    dimensionCoveragePercent: coverage.dimension ?? (allVerified ? 100 : 0),
+    enforcementScenarios: sumEnforcementScenarios(datasourceRows),
+    datasourceRows
+  };
+}
+
+module.exports = {
+  runGovernanceVerifyForExternalSystem
+};

package/lib/commands/governance.js

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Integration validation scenario packs — governance command family (424.0).
+ */
+
+'use strict';
+
+const {
+  collectString,
+  governanceGenerateHandler,
+  governanceVerifyHandler,
+  governanceUploadHandler,
+  governanceDownloadHandler
+} = require('./governance-command-action');
+const {
+  GOVERNANCE_GENERATE_HELP_AFTER,
+  GOVERNANCE_VERIFY_HELP_AFTER,
+  GOVERNANCE_UPLOAD_HELP_AFTER,
+  GOVERNANCE_DOWNLOAD_HELP_AFTER,
+  GOVERNANCE_PARENT_HELP_AFTER
+} = require('../cli/setup-certification.help');
+
+const SHARED_OPTS = [
+  ['-e, --env <env>', 'Environment: dev, tst, or pro', 'dev'],
+  ['--no-sync', 'Skip publishing local integration files before dataplane calls'],
+  [
+    '--force',
+    'With default sync, pass force to upload (same as aifabrix upload --force)'
+  ]
+];
+
+/**
+ * @param {import('commander').Command} cmd
+ */
+function applySharedGovernanceOpts(cmd) {
+  for (const [flags, desc, defaultValue] of SHARED_OPTS) {
+    cmd.option(flags, desc, defaultValue);
+  }
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceGenerate(governance) {
+  const cmd = governance
+    .command('generate <systemKey>')
+    .description('Generate integration validation scenario packs on the dataplane')
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile (bronze, silver, gold, …)',
+      'bronze'
+    )
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--max-samples-per-partition <n>',
+      'Max keys per mustInclude/mustExclude partition',
+      '25'
+    )
+    .option('-v, --verbose', 'Verbose output')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_GENERATE_HELP_AFTER)
+    .action(governanceGenerateHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceVerify(governance) {
+  const cmd = governance
+    .command('verify <systemKey>')
+    .description('Run persisted scenario packs (governance:evaluate)')
+    .option(
+      '--pack <path>',
+      'Authoring override: local scenario pack YAML instead of dataplane active pack'
+    )
+    .option('-a, --app <path>', 'Integration folder override (with --pack)')
+    .option('--scenario <id>', 'Scenario subset when using --pack (repeatable)', collectString, [])
+    .option('-v, --verbose', 'Per-datasource breakdown')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_VERIFY_HELP_AFTER)
+    .action(governanceVerifyHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceUpload(governance) {
+  const cmd = governance
+    .command('upload <systemKey>')
+    .description('Upload integration/<systemKey>/scenarios/*.yaml to the dataplane')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_UPLOAD_HELP_AFTER)
+    .action(governanceUploadHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceDownload(governance) {
+  const cmd = governance
+    .command('download <systemKey>')
+    .description('Download active packs to integration/<systemKey>/scenarios/')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_DOWNLOAD_HELP_AFTER)
+    .action(governanceDownloadHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupGovernanceCommands(program) {
+  const governance = program
+    .command('governance')
+    .description(
+      'Integration validation scenario packs (generate, verify, download, upload)'
+    )
+    .addHelpText('after', GOVERNANCE_PARENT_HELP_AFTER);
+
+  applySharedGovernanceOpts(governance);
+
+  registerGovernanceGenerate(governance);
+  registerGovernanceVerify(governance);
+  registerGovernanceUpload(governance);
+  registerGovernanceDownload(governance);
+}
+
+module.exports = {
+  setupGovernanceCommands,
+  collectString
+};

package/lib/commands/identity-apply-sync.js

@@ -7,14 +7,15 @@
 'use strict';
 
 const logger = require('../utils/logger');
-const { formatBlockingError, formatSuccessLine } = require('../utils/cli-layout-chalk');
+const { formatSuccessLine, headerKeyValue } = require('../utils/cli-layout-chalk');
 const {
   resolveControllerAndAuth,
   resolveEnvKey,
   requireNonEmpty,
   unwrapControllerData,
   throwIfApiFailed,
-  assertSyncStatsOk
+  assertSyncStatsOk,
+  logIdentityCliError
 } = require('./identity-shared');
 const { clearAuthCache } = require('../api/auth-cache.api');
 const { fullSyncToDataplane } = require('../api/dataplane-sync.api');
@@ -70,7 +71,7 @@ function setupIdentityApplyCommand(identityCmd) {
           );
         }
       } catch (e) {
-        logger.error(formatBlockingError(e.message));
+        logIdentityCliError(e.message);
         process.exit(1);
       }
     });
@@ -103,6 +104,46 @@ async function maybePurgeCache(controllerUrl, authConfig, purgeCache) {
   logger.log(formatSuccessLine('Controller cache cleared'));
 }
 
+/**
+ * @param {string} controllerUrl
+ * @param {string} envKey
+ * @param {Object} authConfig
+ * @returns {Promise<string>}
+ */
+async function resolveSyncDataplaneUrl(controllerUrl, envKey, authConfig) {
+  try {
+    const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+    return await resolveDataplaneUrl(controllerUrl, envKey, authConfig, { silent: true });
+  } catch {
+    return '—';
+  }
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.controllerUrl
+ * @param {string} params.envKey
+ * @param {Object} params.authConfig
+ * @param {Object|null|undefined} params.stats
+ */
+async function printIdentitySyncSuccess({ controllerUrl, envKey, authConfig, stats }) {
+  const dataplaneUrl = await resolveSyncDataplaneUrl(controllerUrl, envKey, authConfig);
+  const usersProcessed = Number(stats?.usersProcessed ?? 0);
+  const groupsProcessed = Number(stats?.groupsProcessed ?? 0);
+  const syncErrors = Number(stats?.errors ?? 0);
+
+  logger.log('');
+  logger.log(formatSuccessLine(`Identity synced to dataplane (${envKey})`));
+  logger.log(headerKeyValue('  Controller:', controllerUrl));
+  logger.log(headerKeyValue('  Dataplane:', dataplaneUrl));
+  logger.log('');
+  logger.log(`  Users:   ${usersProcessed} processed`);
+  logger.log(`  Groups:  ${groupsProcessed} processed`);
+  if (syncErrors > 0) {
+    logger.log(`  Errors:  ${syncErrors}`);
+  }
+}
+
 async function runIdentitySyncAction(options) {
   try {
     const { controllerUrl, authConfig } = await resolveControllerAndAuth();
@@ -116,16 +157,16 @@ async function runIdentitySyncAction(options) {
       printJson(stats);
       return;
     }
-    logger.log(formatSuccessLine(`Identity synced to dataplane (${envKey})`));
-    logger.log(`  usersProcessed=${stats?.usersProcessed ?? 0}`);
-    logger.log(`  groupsProcessed=${stats?.groupsProcessed ?? 0}`);
+    await printIdentitySyncSuccess({ controllerUrl, envKey, authConfig, stats });
   } catch (e) {
-    logger.error(formatBlockingError(e.message));
+    logIdentityCliError(e.message);
     process.exit(1);
   }
 }
 
 module.exports = {
   setupIdentityApplyCommand,
-  setupIdentitySyncCommand
+  setupIdentitySyncCommand,
+  printIdentitySyncSuccess,
+  resolveSyncDataplaneUrl
 };

package/lib/commands/identity-group-cli.js

@@ -7,7 +7,7 @@
 'use strict';
 
 const logger = require('../utils/logger');
-const { formatBlockingError, formatSuccessLine, headerKeyValue } = require('../utils/cli-layout-chalk');
+const { formatBlockingError, formatSuccessLine } = require('../utils/cli-layout-chalk');
 const {
   resolveControllerAndAuth,
   requireNonEmpty,
@@ -15,11 +15,26 @@ const {
   throwIfApiFailed
 } = require('./identity-shared');
 const { listGroups, getGroup, createGroup, listGroupMembers } = require('../api/groups.api');
+const {
+  extractPaginatedList,
+  printGroupMembersTable,
+  printGroupRecord,
+  printIdentityEmpty,
+  printIdentityListHeader,
+  printIdentityNotFound,
+  printIdentityTable,
+  printListPaginationFooter,
+  GROUP_LIST_COLUMNS
+} = require('../identity/identity-display');
 
 function printJson(data) {
   logger.log(JSON.stringify(data, null, 2));
 }
 
+function groupNotFoundHints() {
+  return ['af identity group list --search <text>', 'Use group name or id from group list'];
+}
+
 function registerGroupCreate(groupCmd) {
   groupCmd
     .command('create')
@@ -51,7 +66,7 @@ function registerGroupList(groupCmd) {
     .description('List groups')
     .option('--page <n>', 'Page', (v) => parseInt(v, 10))
     .option('--page-size <n>', 'Page size', (v) => parseInt(v, 10))
-    .option('--search <text>', 'Search groups')
+    .option('--search <text>', 'Search groups by name or display name')
     .option('--json', 'JSON output')
     .action(async(options) => {
       try {
@@ -62,14 +77,24 @@ function registerGroupList(groupCmd) {
           search: options.search
         });
         throwIfApiFailed(res);
-        const data = unwrapControllerData(res);
         if (options.json) {
-          printJson(data);
+          printJson(res.data ?? res);
           return;
         }
-        const items = Array.isArray(data) ? data : data?.data || [];
-        items.forEach((g) => logger.log(`  ${g.id}  ${g.name}`));
-        logger.log('');
+        const { items, meta } = extractPaginatedList(res);
+        printIdentityListHeader({
+          emoji: '👥',
+          title: 'Groups',
+          context: controllerUrl,
+          shown: items.length,
+          total: meta?.totalItems ?? items.length
+        });
+        if (items.length === 0) {
+          printIdentityEmpty('No groups found.', ['Try --search']);
+          return;
+        }
+        printIdentityTable(GROUP_LIST_COLUMNS, items);
+        printListPaginationFooter(meta);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -79,22 +104,28 @@ function registerGroupList(groupCmd) {
 
 function registerGroupGet(groupCmd) {
   groupCmd
-    .command('get <idOrName>')
+    .command('get <groupIdOrName>')
     .description('Get group by id or name')
     .option('--json', 'JSON output')
-    .action(async(idOrName, options) => {
+    .action(async(groupIdOrName, options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await getGroup(controllerUrl, authConfig, requireNonEmpty(idOrName, 'idOrName'));
-        throwIfApiFailed(res);
+        const value = requireNonEmpty(groupIdOrName, 'groupIdOrName');
+        const res = await getGroup(controllerUrl, authConfig, value);
+        if (!res || res.success === false) {
+          printIdentityNotFound('Group', value, groupNotFoundHints());
+          process.exit(1);
+        }
         const row = unwrapControllerData(res);
+        if (!row?.id) {
+          printIdentityNotFound('Group', value, groupNotFoundHints());
+          process.exit(1);
+        }
         if (options.json) {
           printJson(row);
           return;
         }
-        logger.log(headerKeyValue('Id:', row.id));
-        logger.log(headerKeyValue('Name:', row.name));
-        logger.log('');
+        printGroupRecord(row);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -104,26 +135,35 @@ function registerGroupGet(groupCmd) {
 
 function registerGroupMembers(groupCmd) {
   groupCmd
-    .command('members <idOrName>')
+    .command('members <groupIdOrName>')
     .description('List members of a group')
     .option('--json', 'JSON output')
-    .action(async(idOrName, options) => {
+    .action(async(groupIdOrName, options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await listGroupMembers(
-          controllerUrl,
-          authConfig,
-          requireNonEmpty(idOrName, 'idOrName')
-        );
-        throwIfApiFailed(res);
+        const value = requireNonEmpty(groupIdOrName, 'groupIdOrName');
+        const res = await listGroupMembers(controllerUrl, authConfig, value);
+        if (!res || res.success === false) {
+          printIdentityNotFound('Group', value, groupNotFoundHints());
+          process.exit(1);
+        }
         const data = unwrapControllerData(res);
+        const items = Array.isArray(data) ? data : data?.data || [];
         if (options.json) {
-          printJson(data);
+          printJson(items);
           return;
         }
-        const items = Array.isArray(data) ? data : data?.data || [];
-        items.forEach((m) => logger.log(`  ${m.userId || m.id}  ${m.email || ''}`));
-        logger.log('');
+        printIdentityListHeader({
+          emoji: '👤',
+          title: `Members of ${value}`,
+          shown: items.length,
+          total: items.length
+        });
+        if (items.length === 0) {
+          printIdentityEmpty('No members in this group.');
+          return;
+        }
+        printGroupMembersTable(items);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);

package/lib/commands/identity-membership-role-cache.js

@@ -19,30 +19,43 @@ const {
 const { addUserToGroup, removeUserFromGroup } = require('../api/user-groups.api');
 const { listEnvironmentRoles, updateRoleGroups } = require('../api/environments.api');
 const { clearAuthCache, invalidateAuthCache } = require('../api/auth-cache.api');
+const {
+  printIdentityEmpty,
+  printIdentityListHeader,
+  printIdentityTable
+} = require('../identity/identity-display');
 
 function printJson(data) {
   logger.log(JSON.stringify(data, null, 2));
 }
 
+const ROLE_LIST_COLUMNS = [
+  { label: 'Role', width: 36, value: (r) => r.value || r.role || r.name || '—' },
+  {
+    label: 'Groups',
+    width: 44,
+    value: (r) => {
+      const groups = Array.isArray(r.groups) ? r.groups.filter(Boolean) : [];
+      return groups.length > 0 ? groups.join(', ') : '—';
+    }
+  }
+];
+
 /**
  * @param {import('commander').Command} memCmd
  */
 function setupIdentityMembershipCommands(memCmd) {
   memCmd
-    .command('add <userId> <groupId>')
-    .description('Add user to group (controller ids)')
-    .action(async(userId, groupId) => {
+    .command('add <userIdOrEmail> <groupIdOrName>')
+    .description('Add user to group (id, email, username + group id or name)')
+    .action(async(userIdOrEmail, groupIdOrName) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await addUserToGroup(
-          controllerUrl,
-          authConfig,
-          requireNonEmpty(userId, 'userId'),
-          requireNonEmpty(groupId, 'groupId'),
-          {}
-        );
+        const userRef = requireNonEmpty(userIdOrEmail, 'userIdOrEmail');
+        const groupRef = requireNonEmpty(groupIdOrName, 'groupIdOrName');
+        const res = await addUserToGroup(controllerUrl, authConfig, userRef, groupRef, {});
         throwIfApiFailed(res);
-        logger.log(formatSuccessLine(`Membership created: ${userId} → ${groupId}`));
+        logger.log(formatSuccessLine(`Membership created: ${userRef} → ${groupRef}`));
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -50,19 +63,16 @@ function setupIdentityMembershipCommands(memCmd) {
     });
 
   memCmd
-    .command('remove <userId> <groupId>')
+    .command('remove <userIdOrEmail> <groupIdOrName>')
     .description('Remove user from group')
-    .action(async(userId, groupId) => {
+    .action(async(userIdOrEmail, groupIdOrName) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await removeUserFromGroup(
-          controllerUrl,
-          authConfig,
-          requireNonEmpty(userId, 'userId'),
-          requireNonEmpty(groupId, 'groupId')
-        );
+        const userRef = requireNonEmpty(userIdOrEmail, 'userIdOrEmail');
+        const groupRef = requireNonEmpty(groupIdOrName, 'groupIdOrName');
+        const res = await removeUserFromGroup(controllerUrl, authConfig, userRef, groupRef);
         throwIfApiFailed(res);
-        logger.log(formatSuccessLine(`Membership removed: ${userId} → ${groupId}`));
+        logger.log(formatSuccessLine(`Membership removed: ${userRef} → ${groupRef}`));
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -73,29 +83,40 @@ function setupIdentityMembershipCommands(memCmd) {
 /**
  * @param {import('commander').Command} roleCmd
  */
+async function handleRoleListAction(options) {
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth();
+  const envKey = await resolveEnvKey(options);
+  const res = await listEnvironmentRoles(controllerUrl, envKey, authConfig);
+  throwIfApiFailed(res);
+  const data = unwrapControllerData(res);
+  if (options.json) {
+    printJson(data);
+    return;
+  }
+  const items = Array.isArray(data) ? data : data?.data || data?.roles || [];
+  printIdentityListHeader({
+    emoji: '🔐',
+    title: 'Role → group mappings',
+    context: `environment: ${envKey}`,
+    shown: (items || []).length,
+    total: (items || []).length
+  });
+  if (!items || items.length === 0) {
+    printIdentityEmpty('No roles found for this environment.');
+    return;
+  }
+  printIdentityTable(ROLE_LIST_COLUMNS, items);
+}
+
 function setupIdentityRoleCommands(roleCmd) {
   roleCmd
     .command('list')
     .description('List roles and group mappings for an environment')
-    .requiredOption('-e, --env <key>', 'Environment key (dev, tst, pro)')
+    .option('-e, --env <key>', 'Environment key (defaults from aifabrix config)')
     .option('--json', 'JSON output')
     .action(async(options) => {
       try {
-        const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const envKey = await resolveEnvKey(options);
-        const res = await listEnvironmentRoles(controllerUrl, envKey, authConfig);
-        throwIfApiFailed(res);
-        const data = unwrapControllerData(res);
-        if (options.json) {
-          printJson(data);
-          return;
-        }
-        const items = Array.isArray(data) ? data : data?.data || data?.roles || [];
-        (items || []).forEach((r) => {
-          const groups = Array.isArray(r.groups) ? r.groups.join(', ') : '';
-          logger.log(`  ${r.value || r.role || r.name}  →  ${groups || '—'}`);
-        });
-        logger.log('');
+        await handleRoleListAction(options);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -105,7 +126,7 @@ function setupIdentityRoleCommands(roleCmd) {
   roleCmd
     .command('set-groups <roleValue>')
     .description('Map role to groups in an environment')
-    .requiredOption('-e, --env <key>', 'Environment key')
+    .option('-e, --env <key>', 'Environment key (defaults from aifabrix config)')
     .requiredOption('--groups <names>', 'Comma-separated group names')
     .action(async(roleValue, options) => {
       try {

package/lib/commands/identity-shared.js

@@ -6,6 +6,9 @@
 
 'use strict';
 
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-layout-chalk');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { normalizeControllerUrl, resolveEnvironment } = require('../core/config');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
@@ -82,6 +85,23 @@ function parseGroupsList(groupsArg) {
   return parts;
 }
 
+/**
+ * Print a blocking CLI error with optional multi-line guidance in gray.
+ *
+ * @param {string} message
+ * @returns {void}
+ */
+function logIdentityCliError(message) {
+  const lines = String(message || '').split('\n');
+  const head = lines[0] || 'Request failed';
+  logger.error(formatBlockingError(head));
+  lines.slice(1).forEach((line) => {
+    if (line.trim()) {
+      logger.log(chalk.gray(line));
+    }
+  });
+}
+
 module.exports = {
   resolveControllerAndAuth,
   resolveEnvKey,
@@ -90,5 +110,6 @@ module.exports = {
   unwrapControllerData,
   throwIfApiFailed,
   assertSyncStatsOk,
-  apiErrorMessage
+  apiErrorMessage,
+  logIdentityCliError
 };