@aifabrix/builder 2.44.5 → 2.45.0

package/lib/cli/setup-infra.js

@@ -1,4 +1,9 @@
-const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatProgress,
+  formatSuccessLine,
+  sectionTitle,
+  headerKeyValue
+} = require('../utils/cli-test-layout-chalk');
 /**
  * CLI infrastructure command setup (up-infra, up-platform, up-miso, up-dataplane, down-infra, doctor, status, restart).
  *
@@ -7,30 +12,36 @@ const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
 const infra = require('../infrastructure');
 const appLib = require('../app');
-const validator = require('../validation/validator');
 const config = require('../core/config');
 const logger = require('../utils/logger');
-const { handleCommandError, isAuthenticationError } = require('../utils/cli-utils');
-const { resolveControllerUrl } = require('../utils/controller-url');
-const { handleLogin } = require('../commands/login');
+const { handleCommandError } = require('../utils/cli-utils');
 const { handleUpMiso } = require('../commands/up-miso');
-const { handleUpDataplane } = require('../commands/up-dataplane');
-const { applyUpPlatformForceConfig, cleanBuilderAppDirs } = require('../commands/up-common');
+const { cleanBuilderAppDirs } = require('../commands/up-common');
+const { runGuidedUpInfra, runGuidedUpMiso, runGuidedDownInfra } = require('./infra-guided');
 const {
   loadInfraStatusSummary,
   formatInfraStatusTitleLine,
   logInfraStatusConfigurationSummary,
   logPaddedFieldRow
 } = require('../utils/infra-status-display');
+const { runDoctorCheck } = require('./doctor-check');
+const {
+  getRestartableInfraServiceNames,
+  buildRestartInfraHelpLines
+} = require('../constants/infra-compose-service-names');
+
+const {
+  computeEffectiveInfraOptionalFlags,
+  persistMissingInfraOptionalServiceFlags
+} = require('../utils/infra-optional-service-flags');
 
 const UP_INFRA_HELP_AFTER = `
 Typical sequence:
   $ aifabrix up-infra
   $ aifabrix up-platform
-  Or: aifabrix up-miso, then aifabrix up-dataplane (login required for dataplane)
+  Or: aifabrix up-infra, aifabrix up-miso, then aifabrix up-dataplane (login required for dataplane)
 
 Full bootstrap example (Traefik, TLS flag, pgAdmin, catalog overrides — matches shipped defaults in infra.parameter.yaml):
   $ aifabrix up-infra --traefik --tls --adminPassword admin123 --adminEmail admin@aifabrix.dev --userPassword user123 --pgAdmin
@@ -59,29 +70,14 @@ async function persistTlsEnabledFlag(cfg, value) {
   await config.saveConfig(cfg);
   const tlsStr = value ? 'true' : 'false';
   const httpStr = value ? 'false' : 'true';
-  logger.log(
-    chalk.green(
-      `✔ TLS mode ${value ? 'enabled' : 'disabled'} and saved to config (` +
-        '${TLS_ENABLED}=' +
-        tlsStr +
-        ', ${HTTP_ENABLED}=' +
-        httpStr +
-        ' when generating deployment JSON)'
-    )
-  );
-}
-
-/**
- * Resolves effective boolean from option vs config.
- * @param {*} optValue - options.traefik | options.pgAdmin | options.redisAdmin
- * @param {*} cfgValue - cfg.traefik | cfg.pgadmin | cfg.redisCommander
- * @param {boolean} defaultWhenUndef - Default when config value is undefined
- * @returns {boolean}
- */
-function resolveFlag(optValue, cfgValue, defaultWhenUndef = true) {
-  if (optValue === true) return true;
-  if (optValue === false) return false;
-  return cfgValue !== false && (cfgValue === true || defaultWhenUndef);
+  logger.log(formatSuccessLine(
+    `TLS mode ${value ? 'enabled' : 'disabled'} and saved to config (` +
+      '${TLS_ENABLED}=' +
+      tlsStr +
+      ', ${HTTP_ENABLED}=' +
+      httpStr +
+      ' when generating deployment JSON)'
+  ));
 }
 
 /**
@@ -140,16 +136,18 @@ async function runUpInfraCommand(options) {
   await maybePersistTlsFromUpInfra(options, cfg);
   const adminPass = options.adminPassword || options.adminPwd;
   const tlsEnabledEffective = cfg.tlsEnabled === true;
+  const effective = computeEffectiveInfraOptionalFlags(cfg, options);
   await infra.startInfra(developerId, {
-    traefik: resolveFlag(options.traefik, cfg.traefik, false),
-    pgadmin: resolveFlag(options.pgAdmin, cfg.pgadmin, true),
-    redisCommander: resolveFlag(options.redisAdmin, cfg.redisCommander, true),
+    traefik: effective.traefik,
+    pgadmin: effective.pgadmin,
+    redisCommander: effective.redisCommander,
     adminPassword: adminPass,
     adminPwd: adminPass,
     adminEmail: options.adminEmail,
     userPassword: options.userPassword,
     tlsEnabled: tlsEnabledEffective
   });
+  await persistMissingInfraOptionalServiceFlags(cfg, effective);
 }
 
 function setupUpInfraCommand(program) {
@@ -157,6 +155,7 @@ function setupUpInfraCommand(program) {
     .description('Start Postgres, Redis; optional pgAdmin, Redis Commander, Traefik')
     .addHelpText('after', UP_INFRA_HELP_AFTER)
     .option('-d, --developer <id>', 'Set developer ID and start infrastructure')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .option('--adminPassword <password>', 'Override {{adminPassword}} defaults (Postgres, pgAdmin, Redis Commander, catalog literals)')
     .option('--adminEmail <email>', 'Override {{adminEmail}} default (e.g. pgAdmin login email)')
     .option('--userPassword <password>', 'Override {{userPassword}} default (e.g. Keycloak default user password)')
@@ -169,9 +168,28 @@ function setupUpInfraCommand(program) {
     .option('--tls', 'Enable TLS mode; save tlsEnabled (${TLS_ENABLED}=true, ${HTTP_ENABLED}=false in application.yaml)')
     .option('--no-tls', 'Disable TLS mode (${TLS_ENABLED}=false, ${HTTP_ENABLED}=true)')
     .action(async(options) => {
+      const startedAt = new Date();
+      const { recordInfraInstallationCommand } = require('./installation-log-command');
       try {
-        await runUpInfraCommand(options);
+        if (!options.verbose) {
+          await runGuidedUpInfra(options, runUpInfraCommand);
+        } else {
+          await runUpInfraCommand(options);
+        }
+        await recordInfraInstallationCommand({
+          command: 'up-infra',
+          options,
+          startedAt,
+          outcome: 'success'
+        });
       } catch (error) {
+        await recordInfraInstallationCommand({
+          command: 'up-infra',
+          options,
+          startedAt,
+          outcome: 'failure',
+          error
+        });
         handleCommandError(error, 'up-infra');
         process.exit(1);
       }
@@ -184,34 +202,15 @@ function setupUpPlatformCommand(program) {
     .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1, dataplane=myreg/d:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
+    .option('--base', 'Resolve platform images from manifest only (default: true)', true)
+    .option('--verbose', 'Show full orchestration output (default is guided installer)')
     .option(
       '-f, --force',
       'Reset CLI auth (clear all device/client tokens, set environment to dev, set default controller URL from developer-id), clean builder/keycloak, builder/miso-controller, builder/dataplane, then re-fetch from templates'
     )
-    .action(async(options) => {
-      try {
-        if (options.force) {
-          await applyUpPlatformForceConfig();
-          await cleanBuilderAppDirs(['keycloak', 'miso-controller', 'dataplane']);
-        }
-        await handleUpMiso(options);
-        await handleUpDataplane(options);
-      } catch (error) {
-        if (isAuthenticationError(error)) {
-          const controllerUrl = error.controllerUrl || await resolveControllerUrl();
-          logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
-          try {
-            await handleLogin({ method: 'device', controller: controllerUrl });
-            await handleUpDataplane(options);
-            return;
-          } catch (loginOrRetryError) {
-            handleCommandError(loginOrRetryError, 'up-platform');
-            process.exit(1);
-          }
-        }
-        handleCommandError(error, 'up-platform');
-        process.exit(1);
-      }
+    .action((options) => {
+      const { handleUpPlatformCliAction } = require('./setup-infra-up-platform-action');
+      return handleUpPlatformCliAction(options);
     });
 }
 
@@ -221,14 +220,41 @@ function setupUpMisoCommand(program) {
     .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
+    .option('--base', 'Resolve platform images from manifest only (default: true)', true)
     .option('-f, --force', 'Clean builder/keycloak and builder/miso-controller and re-fetch from templates')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .action(async(options) => {
+      const startedAt = new Date();
+      const { recordInfraInstallationCommand } = require('./installation-log-command');
+      let cleanedAppKeys = [];
       try {
         if (options.force) {
-          await cleanBuilderAppDirs(['keycloak', 'miso-controller']);
+          const c = await cleanBuilderAppDirs(['keycloak', 'miso-controller']);
+          cleanedAppKeys = Array.isArray(c) ? c : [];
+        }
+        if (!options.verbose) {
+          await runGuidedUpMiso(options, handleUpMiso);
+        } else {
+          await handleUpMiso(options);
         }
-        await handleUpMiso(options);
+        await recordInfraInstallationCommand({
+          command: 'up-miso',
+          options,
+          startedAt,
+          outcome: 'success',
+          platformAppList: ['keycloak', 'miso-controller'],
+          cleanup: cleanedAppKeys.length > 0 ? { cleanedAppKeys } : undefined
+        });
       } catch (error) {
+        await recordInfraInstallationCommand({
+          command: 'up-miso',
+          options,
+          startedAt,
+          outcome: 'failure',
+          error,
+          platformAppList: ['keycloak', 'miso-controller'],
+          cleanup: cleanedAppKeys.length > 0 ? { cleanedAppKeys } : undefined
+        });
         handleCommandError(error, 'up-miso');
         process.exit(1);
       }
@@ -237,33 +263,16 @@ function setupUpMisoCommand(program) {
 
 function setupUpDataplaneCommand(program) {
   program.command('up-dataplane')
-    .description('Register, deploy, run dataplane locally (dev env; login required)')
+    .description('Register, deploy, run dataplane locally (dev env; needs up-infra; login required)')
     .option('-r, --registry <url>', 'Override registry for dataplane image')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <ref>', 'Override dataplane image reference (e.g. myreg/dataplane:latest)')
+    .option('--base', 'Resolve dataplane image from manifest only when running locally (default: true)', true)
     .option('-f, --force', 'Clean builder/dataplane and re-fetch from templates')
-    .action(async(options) => {
-      try {
-        if (options.force) {
-          await cleanBuilderAppDirs(['dataplane']);
-        }
-        await handleUpDataplane(options);
-      } catch (error) {
-        if (isAuthenticationError(error)) {
-          const controllerUrl = error.controllerUrl || await resolveControllerUrl();
-          logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
-          try {
-            await handleLogin({ method: 'device', controller: controllerUrl });
-            await handleUpDataplane(options);
-            return;
-          } catch (loginOrRetryError) {
-            handleCommandError(loginOrRetryError, 'up-dataplane');
-            process.exit(1);
-          }
-        }
-        handleCommandError(error, 'up-dataplane');
-        process.exit(1);
-      }
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
+    .action((options) => {
+      const { handleUpDataplaneCliAction } = require('./setup-infra-up-dataplane-action');
+      return handleUpDataplaneCliAction(options);
     });
 }
 
@@ -271,8 +280,14 @@ function setupDownInfraCommand(program) {
   program.command('down-infra [service|app]')
     .description('Stop all infra, or stop one app; use -v to remove volumes')
     .option('-v, --volumes', 'Remove volumes (deletes all data)')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .action(async(appName, options) => {
       try {
+        if (!options.verbose) {
+          await runGuidedDownInfra(appName, options, infra, appLib);
+          return;
+        }
+
         if (typeof appName === 'string' && appName.trim().length > 0) {
           await appLib.downApp(appName, { volumes: !!options.volumes });
         } else {
@@ -291,33 +306,7 @@ function setupDoctorCommand(program) {
     .description('Check Docker, ports, secrets, and infra health')
     .action(async() => {
       try {
-        const result = await validator.checkEnvironment();
-        logger.log('\n🔍 AI Fabrix Environment Check\n');
-        logger.log(`Docker: ${result.docker === 'ok' ? '✔ Running' : '✖ Not available'}`);
-        logger.log(`Ports: ${result.ports === 'ok' ? '✔ Available' : '⚠  Some ports in use'}`);
-        logger.log(`Secrets: ${result.secrets === 'ok' ? '✔ Configured' : '✖ Missing'}`);
-        if (result.recommendations.length > 0) {
-          logger.log('\n📋 Recommendations:');
-          result.recommendations.forEach(rec => logger.log(`  • ${rec}`));
-        }
-        if (result.docker === 'ok') {
-          try {
-            const cfg = await config.getConfig();
-            const health = await infra.checkInfraHealth(null, {
-              pgadmin: cfg.pgadmin !== false,
-              redisCommander: cfg.redisCommander !== false,
-              traefik: !!cfg.traefik
-            });
-            logger.log('\n🏥 Infrastructure Health:');
-            Object.entries(health).forEach(([service, status]) => {
-              const icon = status === 'healthy' ? '✔' : status === 'unknown' ? '❓' : '✖';
-              logger.log(`  ${icon} ${service}: ${status}`);
-            });
-          } catch (error) {
-            logger.log('\n🏥 Infrastructure: Not running');
-          }
-        }
-        logger.log('');
+        await runDoctorCheck();
       } catch (error) {
         handleCommandError(error, 'doctor');
         process.exit(1);
@@ -365,19 +354,44 @@ function setupStatusCommand(program) {
     });
 }
 
-const INFRA_SERVICES = ['postgres', 'redis', 'pgadmin', 'redis-commander', 'traefik'];
+const RESTART_INFRA_SERVICE_NAMES = getRestartableInfraServiceNames();
+
+const RESTART_COMMAND_HELP_AFTER = `
+Infra — use these exact Docker Compose service names:
+${buildRestartInfraHelpLines()}
+
+Optional services (pgadmin, redis-commander, traefik) only exist if you enabled them when running up-infra.
+
+Builder apps (examples):
+  keycloak, miso-controller, dataplane
+
+Examples:
+  $ aifabrix restart postgres
+  $ aifabrix restart traefik
+  $ aifabrix restart miso-controller
+`;
 
 function setupRestartCommand(program) {
   program.command('restart <service|app>')
-    .description('Restart infra service (postgres, redis, …) or a builder/<app> container')
+    .description(
+      'Restart one infra compose service (postgres, redis, pgadmin, redis-commander, traefik) or a builder app container'
+    )
+    .addHelpText('after', RESTART_COMMAND_HELP_AFTER)
     .action(async(service) => {
       try {
-        if (INFRA_SERVICES.includes(service)) {
-          await infra.restartService(service);
-          logger.log(`✔ ${service} service restarted successfully`);
+        if (RESTART_INFRA_SERVICE_NAMES.includes(service)) {
+          logger.log('');
+          logger.log(sectionTitle('Restart'));
+          logger.log(headerKeyValue('Infra service:', service));
+          logger.log(formatProgress(`Restarting ${service}…`));
+          await infra.restartService(service, { suppressProgressLog: true });
+          logger.log(formatSuccessLine(`${service} restarted successfully`));
         } else {
+          logger.log('');
+          logger.log(sectionTitle('Restart'));
+          logger.log(headerKeyValue('Application:', service));
           await appLib.restartApp(service);
-          logger.log(`✔ ${service} restarted successfully`);
+          logger.log(formatSuccessLine(`${service} restarted successfully`));
         }
       } catch (error) {
         handleCommandError(error, 'restart');

package/lib/cli/setup-integration-client.js

@@ -0,0 +1,182 @@
+/**
+ * CLI integration-client command setup (Controller OAuth / API clients).
+ *
+ * @fileoverview Integration client CLI definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  runIntegrationClientCreate,
+  runIntegrationClientList,
+  runIntegrationClientRotateSecret,
+  runIntegrationClientDelete,
+  runIntegrationClientUpdateGroups,
+  runIntegrationClientUpdateRedirectUris
+} = require('../commands/integration-client');
+
+const HELP_AFTER = `
+Integration clients are machine identities for integrations, CI, Postman OAuth2, or API access.
+Use: list (integration-client:read), create (integration-client:create), rotate-secret,
+update-groups, update-redirect-uris (integration-client:update), delete (integration-client:delete).
+The controller returns a one-time clientSecret on create and rotate-secret—save it immediately;
+it cannot be retrieved again.
+
+Examples:
+  $ aifabrix integration-client create --key postman --display-name "Postman client" \\
+      --redirect-uris https://oauth.pstmn.io/v1/callback --group-names AI-Fabrix-Platform-Admins
+  $ aifabrix integration-client list
+  $ aifabrix integration-client rotate-secret --id <uuid>
+  $ aifabrix integration-client delete --id <uuid>
+  $ aifabrix integration-client update-groups --id <uuid> --group-names Group1,Group2
+  $ aifabrix integration-client update-redirect-uris --id <uuid> --redirect-uris https://app.example.com/callback
+
+Run "aifabrix login" first.`;
+
+function parseOptionalInt(val) {
+  return (val !== undefined && val !== null) ? parseInt(val, 10) : undefined;
+}
+
+function addCreateCommand(integrationClient) {
+  integrationClient.command('create')
+    .description('Create an integration client and receive a one-time clientSecret (save it now; it will not be shown again)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('-k, --key <key>', 'Stable key (lowercase alphanumeric and hyphens; required)')
+    .option('-n, --display-name <name>', 'Display name (required)')
+    .option('--keycloak-client-id <id>', 'Optional fixed Keycloak client id (when omitted, the server assigns one)')
+    .option('--redirect-uris <uris>', 'Comma-separated OAuth2 redirect URIs (required)')
+    .option('--group-names <names>', 'Comma-separated group names (optional; omit for OAuth-only clients)')
+    .option('-d, --description <description>', 'Optional description')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientCreate({
+          controller: options.controller,
+          key: options.key,
+          displayName: options.displayName,
+          keycloakClientId: options.keycloakClientId,
+          redirectUris: options.redirectUris,
+          groupNames: options.groupNames,
+          description: options.description
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client create');
+        process.exit(1);
+      }
+    });
+}
+
+function addListCommand(integrationClient) {
+  integrationClient.command('list')
+    .description('List integration clients (supports pagination and search)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--page <n>', 'Page number')
+    .option('--page-size <n>', 'Items per page')
+    .option('--search <term>', 'Search term')
+    .option('--sort <field>', 'Sort field/direction')
+    .option('--filter <expr>', 'Filter expression')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientList({
+          controller: options.controller,
+          page: parseOptionalInt(options.page),
+          pageSize: parseOptionalInt(options.pageSize),
+          search: options.search,
+          sort: options.sort,
+          filter: options.filter
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client list');
+        process.exit(1);
+      }
+    });
+}
+
+function addRotateSecretCommand(integrationClient) {
+  integrationClient.command('rotate-secret')
+    .description('Rotate (regenerate) secret for an integration client; new secret shown once only')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientRotateSecret({ controller: options.controller, id: options.id });
+      } catch (error) {
+        handleCommandError(error, 'integration-client rotate-secret');
+        process.exit(1);
+      }
+    });
+}
+
+function addDeleteCommand(integrationClient) {
+  integrationClient.command('delete')
+    .description('Delete (deactivate) an integration client')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientDelete({ controller: options.controller, id: options.id });
+      } catch (error) {
+        handleCommandError(error, 'integration-client delete');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateGroupsCommand(integrationClient) {
+  integrationClient.command('update-groups')
+    .description('Update group assignments for an integration client')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .option('--group-names <names>', 'Comma-separated group names (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientUpdateGroups({
+          controller: options.controller,
+          id: options.id,
+          groupNames: options.groupNames
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client update-groups');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateRedirectUrisCommand(integrationClient) {
+  integrationClient.command('update-redirect-uris')
+    .description('Update redirect URIs for an integration client (min 1)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .option('--redirect-uris <uris>', 'Comma-separated redirect URIs (required, min 1)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientUpdateRedirectUris({
+          controller: options.controller,
+          id: options.id,
+          redirectUris: options.redirectUris
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client update-redirect-uris');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Registers integration-client commands
+ * @param {Command} program - Commander program instance
+ */
+function setupIntegrationClientCommands(program) {
+  const integrationClient = program
+    .command('integration-client')
+    .description('OAuth integration clients on Controller (integrations, CI, API access)')
+    .addHelpText('after', HELP_AFTER);
+  addCreateCommand(integrationClient);
+  addListCommand(integrationClient);
+  addRotateSecretCommand(integrationClient);
+  addDeleteCommand(integrationClient);
+  addUpdateGroupsCommand(integrationClient);
+  addUpdateRedirectUrisCommand(integrationClient);
+}
+
+module.exports = { setupIntegrationClientCommands };

package/lib/cli/setup-parameters.js

@@ -17,11 +17,30 @@ function setupParametersCommands(program) {
 
   parameters
     .command('validate')
-    .description('Check env.template kv:// references against lib/schema/infra.parameter.yaml')
+    .description(
+      'Validate builder/*/env.template kv:// references against infra.parameter.yaml'
+    )
     .option('--catalog <path>', 'Override path to infra.parameter.yaml')
+    .option('--verbose', 'Print scanned files and scan summary')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  aifabrix parameters validate
+  aifabrix parameters validate --verbose
+  aifabrix parameters validate --catalog ./lib/schema/infra.parameter.yaml
+
+Notes:
+  - Scans builder/* apps only (integration/* is intentionally skipped).
+  - Extracts kv://KEY references from env.template and checks KEY coverage in the catalog.
+`
+    )
     .action(async(opts) => {
       try {
-        const result = await handleParametersValidate({ catalogPath: opts.catalog });
+        const result = await handleParametersValidate({
+          catalogPath: opts.catalog,
+          verbose: Boolean(opts.verbose)
+        });
         if (!result.valid) process.exit(1);
       } catch (error) {
         handleCommandError(error, 'parameters validate');