@aifabrix/builder 2.42.1 → 2.43.0

package/lib/cli/setup-auth.js

@@ -60,23 +60,31 @@ function setupAuthSubcommands(program) {
       process.exit(1);
     }
   };
-  const auth = program.command('auth').description('Authentication commands');
-  auth.command('status')
-    .description('Display authentication status for current controller and environment')
-    .option('--validate', 'Exit with code 1 when not authenticated (for scripted use, e.g. manual test setup)')
-    .action(authStatusHandler);
-  auth.command('config')
-    .description('Configure authentication settings (controller, environment)')
-    .option('--set-controller <url>', 'Set default controller URL')
-    .option('--set-environment <env>', 'Set default environment')
+  const auth = program.command('auth')
+    .description('Authentication status and config (controller, environment)')
+    .option('--set-controller <url>', 'Set default controller URL in config')
+    .option('--set-environment <env>', 'Set default environment in config')
     .action(async(options) => {
       try {
-        await handleAuthConfig(options);
+        const setController = options.setController || options['set-controller'];
+        const setEnvironment = options.setEnvironment || options['set-environment'];
+        if (setController || setEnvironment) {
+          await handleAuthConfig({
+            setController,
+            setEnvironment
+          });
+          return;
+        }
+        await handleAuthStatus(options);
       } catch (error) {
-        handleCommandError(error, 'auth config');
+        handleCommandError(error, 'auth');
         process.exit(1);
       }
     });
+  auth.command('status')
+    .description('Display authentication status for current controller and environment')
+    .option('--validate', 'Exit with code 1 when not authenticated (for scripted use, e.g. manual test setup)')
+    .action(authStatusHandler);
 }
 
 /**

package/lib/cli/setup-dev.js

@@ -73,51 +73,26 @@ async function handleSetFormat(format) {
 }
 
 /**
- * Register dev config and set-id commands.
+ * Register dev show and set-id commands.
  * @param {Command} dev - dev subcommand group
  */
-function setupDevConfigCommands(dev) {
+function setupDevShowAndSetId(dev) {
   dev
-    .command('config')
-    .description('Show or set developer configuration')
-    .option('--set-id <id>', 'Set developer ID')
-    .action(async(options) => {
+    .command('show')
+    .description('Show developer configuration (ports and config vars)')
+    .action(async() => {
       try {
-        const setIdValue = options.setId || options['set-id'];
-        if (setIdValue) {
-          const digitsOnly = /^[0-9]+$/.test(setIdValue);
-          if (!digitsOnly) {
-            throw new Error('Developer ID must be a non-negative digit string (0 = default infra, > 0 = developer-specific)');
-          }
-          await config.setDeveloperId(setIdValue);
-          process.env.AIFABRIX_DEVELOPERID = setIdValue;
-          logger.log(chalk.green(`✓ Developer ID set to ${setIdValue}`));
-          await displayDevConfig(setIdValue);
-          return;
-        }
         const devId = await config.getDeveloperId();
         await displayDevConfig(devId);
       } catch (error) {
-        handleCommandError(error, 'dev config');
-        process.exit(1);
-      }
-    });
-
-  dev
-    .command('set-format <format>')
-    .description('Set default output format for download/convert (json | yaml); used when --format not passed')
-    .action(async(format) => {
-      try {
-        await handleSetFormat(format);
-      } catch (error) {
-        handleCommandError(error, 'dev set-format');
+        handleCommandError(error, 'dev show');
         process.exit(1);
       }
     });
 
   dev
     .command('set-id <id>')
-    .description('Set developer ID (convenience alias for "dev config --set-id")')
+    .description('Set developer ID (0 = default infra, > 0 = developer-specific)')
     .action(async(id) => {
       try {
         const digitsOnly = /^[0-9]+$/.test(id);
@@ -135,6 +110,61 @@ function setupDevConfigCommands(dev) {
     });
 }
 
+/**
+ * Register dev set-env-config, set-home and set-format commands.
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevPathAndFormatCommands(dev) {
+  dev
+    .command('set-env-config <filePath>')
+    .description('Set aifabrix-env-config path in config.yaml (pass empty to clear; path is not checked for existence)')
+    .action(async(filePath) => {
+      try {
+        const trimmed = (filePath || '').trim();
+        await config.setAifabrixEnvConfigPath(trimmed);
+        logger.log(trimmed === '' ? chalk.green('✓ Env config path cleared') : chalk.green(`✓ Env config path set to ${trimmed}`));
+      } catch (error) {
+        handleCommandError(error, 'dev set-env-config');
+        process.exit(1);
+      }
+    });
+
+  dev
+    .command('set-home <path>')
+    .description('Set aifabrix-home path in config.yaml (pass empty string to clear)')
+    .action(async(homePath) => {
+      try {
+        const trimmed = (homePath || '').trim();
+        await config.setAifabrixHomeOverride(trimmed);
+        logger.log(trimmed === '' ? chalk.green('✓ Home path cleared') : chalk.green(`✓ Home path set to ${trimmed}`));
+      } catch (error) {
+        handleCommandError(error, 'dev set-home');
+        process.exit(1);
+      }
+    });
+
+  dev
+    .command('set-format <format>')
+    .description('Set default output format for download/convert (json | yaml); used when --format not passed')
+    .action(async(format) => {
+      try {
+        await handleSetFormat(format);
+      } catch (error) {
+        handleCommandError(error, 'dev set-format');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register dev show, set-id, set-env-config, set-home and set-format commands.
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevConfigCommands(dev) {
+  setupDevShowAndSetId(dev);
+  setupDevPathAndFormatCommands(dev);
+}
+
 /**
  * Register dev init and refresh commands.
  * @param {Command} dev - dev subcommand group

package/lib/cli/setup-environment.js

@@ -1,5 +1,5 @@
 /**
- * CLI environment deployment command setup (environment deploy, env deploy).
+ * CLI environment deployment command setup (env deploy).
  *
  * @fileoverview Environment command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
@@ -18,35 +18,20 @@ function setupEnvironmentCommands(program) {
       const environmentDeploy = require('../deployment/environment');
       await environmentDeploy.deployEnvironment(envKey, options);
     } catch (error) {
-      handleCommandError(error, 'environment deploy');
+      handleCommandError(error, 'env deploy');
       process.exit(1);
     }
   };
 
-  const environment = program
-    .command('environment')
-    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
-
   const deployExamples = `
 Examples:
-  $ aifabrix environment deploy dev
-  $ aifabrix environment deploy tst --preset m
-  $ aifabrix environment deploy dev --config ./env-config.json --no-poll`;
-
-  environment
-    .command('deploy <env>')
-    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
-    .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
-    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
-    .option('--skip-validation', 'Skip environment validation')
-    .option('--poll', 'Poll for deployment status', true)
-    .option('--no-poll', 'Do not poll for status')
-    .addHelpText('after', deployExamples)
-    .action(deployEnvHandler);
+  $ aifabrix env deploy dev
+  $ aifabrix env deploy tst --preset m
+  $ aifabrix env deploy dev --config ./env-config.json --no-poll`;
 
   const env = program
     .command('env')
-    .description('Deploy and manage Miso Controller environments (alias for environment)');
+    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
 
   env
     .command('deploy <env>')

package/lib/cli/setup-infra.js

@@ -17,6 +17,7 @@ const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
+const { cleanBuilderAppDirs } = require('../commands/up-common');
 
 /**
  * Persists optional service flag to config when explicitly set.
@@ -108,8 +109,12 @@ 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('-f, --force', 'Clean builder/keycloak, builder/miso-controller, builder/dataplane and re-fetch from templates')
     .action(async(options) => {
       try {
+        if (options.force) {
+          await cleanBuilderAppDirs(['keycloak', 'miso-controller', 'dataplane']);
+        }
         await handleUpMiso(options);
         await handleUpDataplane(options);
       } catch (error) {
@@ -137,8 +142,12 @@ 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('-f, --force', 'Clean builder/keycloak and builder/miso-controller and re-fetch from templates')
     .action(async(options) => {
       try {
+        if (options.force) {
+          await cleanBuilderAppDirs(['keycloak', 'miso-controller']);
+        }
         await handleUpMiso(options);
       } catch (error) {
         handleCommandError(error, 'up-miso');
@@ -153,8 +162,12 @@ function setupUpDataplaneCommand(program) {
     .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('-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)) {

package/lib/cli/setup-secrets.js

@@ -6,12 +6,15 @@
  * @version 2.0.0
  */
 
+const chalk = require('chalk');
 const { handleCommandError } = require('../utils/cli-utils');
 const { handleSecretsSet } = require('../commands/secrets-set');
 const { handleSecretsList } = require('../commands/secrets-list');
 const { handleSecretsRemove } = require('../commands/secrets-remove');
 const { handleSecretsValidate } = require('../commands/secrets-validate');
 const { handleSecure } = require('../commands/secure');
+const config = require('../core/config');
+const logger = require('../utils/logger');
 
 function setupSecretValidateCommand(secretCmd) {
   secretCmd
@@ -20,6 +23,7 @@ function setupSecretValidateCommand(secretCmd) {
     .option('--naming', 'Check key names against *KeyVault convention')
     .action(async(pathArg, options) => {
       try {
+        await config.ensureSecretsEncryptionKey();
         const result = await handleSecretsValidate(pathArg, options);
         if (!result.valid) process.exit(1);
       } catch (error) {
@@ -29,6 +33,25 @@ function setupSecretValidateCommand(secretCmd) {
     });
 }
 
+/**
+ * Registers the secure command on the program.
+ * @param {Command} program - Commander program instance
+ */
+function setupSecureCommand(program) {
+  program.command('secure')
+    .description('Encrypt secrets in secrets.local.yaml files for ISO 27001 compliance')
+    .option('--secrets-encryption <key>', 'Encryption key (32 bytes, hex or base64)')
+    .action(async(options) => {
+      try {
+        await config.ensureSecretsEncryptionKey();
+        await handleSecure(options);
+      } catch (error) {
+        handleCommandError(error, 'secure');
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Sets up secrets and security commands
  * @param {Command} program - Commander program instance
@@ -44,6 +67,7 @@ function setupSecretsCommands(program) {
     .option('--shared', 'List shared secrets (from config aifabrix-secrets or remote API)')
     .action(async(options) => {
       try {
+        await config.ensureSecretsEncryptionKey();
         await handleSecretsList(options);
       } catch (error) {
         handleCommandError(error, 'secret list');
@@ -57,6 +81,7 @@ function setupSecretsCommands(program) {
     .option('--shared', 'Save to general secrets file (from config.yaml aifabrix-secrets) instead of user secrets')
     .action(async(key, value, options) => {
       try {
+        await config.ensureSecretsEncryptionKey();
         await handleSecretsSet(key, value, options);
       } catch (error) {
         handleCommandError(error, 'secret set');
@@ -70,6 +95,7 @@ function setupSecretsCommands(program) {
     .option('--shared', 'Remove from shared secrets (file or remote API)')
     .action(async(key, options) => {
       try {
+        await config.ensureSecretsEncryptionKey();
         await handleSecretsRemove(key, options);
       } catch (error) {
         handleCommandError(error, 'secret remove');
@@ -77,16 +103,29 @@ function setupSecretsCommands(program) {
       }
     });
 
+  setupSecretSetSecretsFileCommand(secretCmd);
   setupSecretValidateCommand(secretCmd);
+  setupSecureCommand(program);
+}
 
-  program.command('secure')
-    .description('Encrypt secrets in secrets.local.yaml files for ISO 27001 compliance')
-    .option('--secrets-encryption <key>', 'Encryption key (32 bytes, hex or base64)')
-    .action(async(options) => {
+/**
+ * Register secret set-secrets-file command.
+ * @param {Command} secretCmd - secret command group
+ */
+function setupSecretSetSecretsFileCommand(secretCmd) {
+  secretCmd
+    .command('set-secrets-file <path>')
+    .description('Set aifabrix-secrets path in config (local file or https URL; pass empty to clear; path/URL is not checked for existence)')
+    .action(async(secretsPath) => {
       try {
-        await handleSecure(options);
+        const trimmed = (secretsPath || '').trim();
+        if (trimmed !== '' && trimmed.startsWith('http://')) {
+          throw new Error('Only https URLs are allowed for remote secrets');
+        }
+        await config.setSecretsPath(trimmed);
+        logger.log(trimmed === '' ? chalk.green('✓ Secrets file path cleared') : chalk.green(`✓ Secrets file path set to ${trimmed}`));
       } catch (error) {
-        handleCommandError(error, 'secure');
+        handleCommandError(error, 'secret set-secrets-file');
         process.exit(1);
       }
     });

package/lib/cli/setup-service-user.js

@@ -10,28 +10,37 @@
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
-const { runServiceUserCreate } = require('../commands/service-user');
+const {
+  runServiceUserCreate,
+  runServiceUserList,
+  runServiceUserRotateSecret,
+  runServiceUserDelete,
+  runServiceUserUpdateGroups,
+  runServiceUserUpdateRedirectUris
+} = require('../commands/service-user');
 
-/**
- * Sets up service-user commands
- * @param {Command} program - Commander program instance
- */
-function setupServiceUserCommands(program) {
-  const serviceUser = program
-    .command('service-user')
-    .description('Create and manage service users (API clients) for integrations and CI')
-    .addHelpText('after', `
+const HELP_AFTER = `
 Service users are dedicated accounts for integrations, CI pipelines, or API clients.
-The controller returns a one-time clientSecret on create—save it immediately; it cannot be retrieved again.
+Use: list (service-user:read), create (service-user:create), rotate-secret, update-groups, update-redirect-uris (service-user:update), delete (service-user:delete).
+The controller returns a one-time clientSecret on create and rotate-secret—save it immediately; it cannot be retrieved again.
 
-Example:
-  $ aifabrix service-user create -u api-client-001 -e api@example.com \\
-      --redirect-uris "https://app.example.com/callback" --group-names "AI-Fabrix-Developers"
+Examples:
+  $ aifabrix service-user create -u postman -e postman@aifabrix.dev \\
+      --redirect-uris https://oauth.pstmn.io/v1/callback --group-names AI-Fabrix-Platform-Admins
+  $ aifabrix service-user list
+  $ aifabrix service-user rotate-secret --id <uuid>
+  $ aifabrix service-user delete --id <uuid>
+  $ aifabrix service-user update-groups --id <uuid> --group-names Group1,Group2
+  $ aifabrix service-user update-redirect-uris --id <uuid> --redirect-uris https://app.example.com/callback
 
-Required: permission service-user:create on the controller. Run "aifabrix login" first.`);
+Run "aifabrix login" first.`;
+
+function parseOptionalInt(val) {
+  return (val !== undefined && val !== null) ? parseInt(val, 10) : undefined;
+}
 
-  serviceUser
-    .command('create')
+function addCreateCommand(serviceUser) {
+  serviceUser.command('create')
     .description('Create a service user 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('-u, --username <username>', 'Service user username (required)')
@@ -41,15 +50,14 @@ Required: permission service-user:create on the controller. Run "aifabrix login"
     .option('-d, --description <description>', 'Description for the service user')
     .action(async(options) => {
       try {
-        const opts = {
+        await runServiceUserCreate({
           controller: options.controller,
           username: options.username,
           email: options.email,
           redirectUris: options.redirectUris,
           groupNames: options.groupNames,
           description: options.description
-        };
-        await runServiceUserCreate(opts);
+        });
       } catch (error) {
         logger.error(chalk.red(`Error: ${error.message}`));
         handleCommandError(error, 'service-user create');
@@ -58,4 +66,122 @@ Required: permission service-user:create on the controller. Run "aifabrix login"
     });
 }
 
+function addListCommand(serviceUser) {
+  serviceUser.command('list')
+    .description('List service users (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 runServiceUserList({
+          controller: options.controller,
+          page: parseOptionalInt(options.page),
+          pageSize: parseOptionalInt(options.pageSize),
+          search: options.search,
+          sort: options.sort,
+          filter: options.filter
+        });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'service-user list');
+        process.exit(1);
+      }
+    });
+}
+
+function addRotateSecretCommand(serviceUser) {
+  serviceUser.command('rotate-secret')
+    .description('Rotate (regenerate) secret for a service user; new secret shown once only')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Service user ID (required)')
+    .action(async(options) => {
+      try {
+        await runServiceUserRotateSecret({ controller: options.controller, id: options.id });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'service-user rotate-secret');
+        process.exit(1);
+      }
+    });
+}
+
+function addDeleteCommand(serviceUser) {
+  serviceUser.command('delete')
+    .description('Delete (deactivate) a service user')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Service user ID (required)')
+    .action(async(options) => {
+      try {
+        await runServiceUserDelete({ controller: options.controller, id: options.id });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'service-user delete');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateGroupsCommand(serviceUser) {
+  serviceUser.command('update-groups')
+    .description('Update group assignments for a service user')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Service user ID (required)')
+    .option('--group-names <names>', 'Comma-separated group names (required)')
+    .action(async(options) => {
+      try {
+        await runServiceUserUpdateGroups({
+          controller: options.controller,
+          id: options.id,
+          groupNames: options.groupNames
+        });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'service-user update-groups');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateRedirectUrisCommand(serviceUser) {
+  serviceUser.command('update-redirect-uris')
+    .description('Update redirect URIs for a service user (min 1)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Service user ID (required)')
+    .option('--redirect-uris <uris>', 'Comma-separated redirect URIs (required, min 1)')
+    .action(async(options) => {
+      try {
+        await runServiceUserUpdateRedirectUris({
+          controller: options.controller,
+          id: options.id,
+          redirectUris: options.redirectUris
+        });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'service-user update-redirect-uris');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Sets up service-user commands
+ * @param {Command} program - Commander program instance
+ */
+function setupServiceUserCommands(program) {
+  const serviceUser = program
+    .command('service-user')
+    .description('Create and manage service users (API clients) for integrations and CI')
+    .addHelpText('after', HELP_AFTER);
+  addCreateCommand(serviceUser);
+  addListCommand(serviceUser);
+  addRotateSecretCommand(serviceUser);
+  addDeleteCommand(serviceUser);
+  addUpdateGroupsCommand(serviceUser);
+  addUpdateRedirectUrisCommand(serviceUser);
+}
+
 module.exports = { setupServiceUserCommands };

package/lib/cli/setup-utility.js

@@ -163,6 +163,7 @@ function setupRepairCommand(program) {
   program.command('repair <app>')
     .description('Repair external integration config: fix drift (file lists, app key, datasource alignment, rbac, manifest)')
     .option('--auth <method>', 'Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template')
+    .option('--doc', 'Regenerate README.md from deployment manifest')
     .option('--dry-run', 'Report changes only; do not write')
     .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
     .option('--expose', 'Set exposed.attributes on each datasource to all fieldMappings.attributes keys')
@@ -174,9 +175,18 @@ function setupRepairCommand(program) {
         const { detectAppType } = require('../utils/paths');
         const { appPath } = await detectAppType(appName);
         logOfflinePathWhenType(appPath);
+        let format = 'yaml';
+        try {
+          const config = require('../core/config');
+          format = (await config.getFormat()) || format;
+        } catch (_) {
+          // use default yaml when config unavailable
+        }
         const result = await repairExternalIntegration(appName, {
           auth: options.auth,
+          doc: options.doc,
           dryRun: options.dryRun,
+          format,
           rbac: options.rbac,
           expose: options.expose,
           sync: options.sync,
@@ -187,6 +197,8 @@ function setupRepairCommand(program) {
           result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
         } else if (result.updated) {
           logger.log(chalk.green('\n✓ Repaired external integration config.'));
+        } else if (result.readmeRegenerated) {
+          logger.log(chalk.green('\n✓ Regenerated README.md from deployment manifest.'));
         } else {
           logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
         }

package/lib/commands/auth-config.js

@@ -55,7 +55,7 @@ async function handleSetController(url) {
 
     throw new Error(
       `You have credentials for another controller (${loggedInControllerUrl}).\n` +
-      `To use ${url} either run "aifabrix login" with that controller, or run "aifabrix logout" first to clear credentials, then set the new controller with --set-controller.`
+      'To use a different controller either run "aifabrix login" with that controller, or run "aifabrix logout" first to clear credentials, then set the new controller with "aifabrix auth --set-controller <url>".'
     );
   } catch (error) {
     logger.error(chalk.red(`✗ Failed to set controller URL: ${error.message}`));
@@ -80,8 +80,7 @@ async function handleSetEnvironment(environment) {
     const controllerUrl = await getControllerUrl();
     if (!controllerUrl) {
       throw new Error(
-        'No controller URL found in config.\n' +
-        'Please run "aifabrix login" first to set the controller URL.'
+        'No controller URL found in config. Run "aifabrix login" first, or set the controller with "aifabrix auth --set-controller <url>".'
       );
     }
 
@@ -89,8 +88,7 @@ async function handleSetEnvironment(environment) {
     const isLoggedIn = await checkUserLoggedIn(controllerUrl);
     if (!isLoggedIn) {
       throw new Error(
-        `You are not logged in to controller ${controllerUrl}.\n` +
-        'Please run "aifabrix login" first to authenticate with this controller.'
+        `You are not logged in to controller ${controllerUrl}. Run "aifabrix login" first to authenticate.`
       );
     }
 
@@ -117,9 +115,7 @@ async function handleSetEnvironment(environment) {
 async function handleAuthConfig(options) {
   if (!options.setController && !options.setEnvironment) {
     throw new Error(
-      'No action specified. Use one of:\n' +
-      '  --set-controller <url>\n' +
-      '  --set-environment <env>'
+      'No action specified. Use "aifabrix auth --set-controller <url>" or "aifabrix auth --set-environment <env>".'
     );
   }
   if (options.setController) {