Fluent Commerce Logo
Docs
Help & Feedback

CLI Active Profile

Essential knowledge

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

30 Apr 2026

Overview

Learn the technical mechanics of the Active Profile feature and how it streamlines CLI workflows. This article details the shift from rigid "Commander-enforced" validation to a flexible "Defaults-first" resolution, allowing implementing partners to work faster without sacrificing accuracy.For the business, this context-aware CLI reduces the learning curve and prevents manual entry errors. Note: While flags are no longer required at the command level (`required: false`), they remain mandatory for execution; the CLI will exit if no context is found.

Key points

  • The Shift: Validation has moved from the Commander parsing stage to the Configuration Utility stage.
  • Precedence: CLI flags always override the Active Profile. If you explicitly pass `--profile`, the active context is ignored for that command.
  • Seamless Integration: The `loadConfigs` utility now calls `resolveDefaults` first to populate missing options before handing them off to existing validation logic.
  • Unchanged Security: Standard validation functions like `loadProfile()` and `checkConfigForAccountProfile()` are still in place; they simply receive their data from a default source if flags are missing.
  • Developer Impact: Task definitions must have `required: true` removed from their options to allow the Active Profile logic to trigger.
  • Error States: If an Active Profile points to a nonexistent profile, the system will catch it during the `loadProfile` phase and exit with a `process.exit(1)`.

The Question

How does the Active Profile feature work with existing tasks that have `required: true` for profile/retailer options?

Current Flow (Before Active Profile)

`1. User runs: fluent module list --profile apsear2dev --retailer ATEST2`
2. Commander parses CLI args
  - Validates required options exist
  - Builds allOpts object: { profile: 'apsear2dev', retailer: 'ATEST2' }
3. Action handler calls configurationUtil.loadConfigs(config, allOpts, modulePath)
4. loadConfigs checks: if (allOpts.profile)
  - Calls loadProfile(allOpts.profile)
  - loadProfile validates profile exists, calls process.exit(1) if not
  - Calls loadRetailer(allOpts.profile, allOpts.retailer)
  - loadRetailer validates retailer exists, calls process.exit(1) if not
5. Task's run() function executes with populated configKey point: Validation happens in TWO places:
  • Commander level: `required: true` ensures flags are provided
  • Configuration level: `loadProfile()` and `loadRetailer()` validate they exist

New Flow (with Active Profile)

Key changes:
  • Remove `required: true` from task option definitions
  • Add Active Profile resolution BEFORE existing validation
  • Existing validation in `loadProfile()` and `loadRetailer()` is UNCHANGED

Error Handling Examples

Scenario 1: No Active Profile set, no flags

`$ fluent module list`

`# Flow:
# 1. allOpts.profile = undefined
# 2. Active Profile doesn't exist
# 3. allOpts.profile still undefined after resolution
# 4. loadConfigs checks: if (allOpts.profile) - FALSE
# 5. config.account is undefined
# 6. Task calls checkConfigForAccountProfile(config)
# 7. Error: "Profile must be set. Use --profile flag or fluent profile use"
`

Scenario 2: Active Profile exists, profile invalid

`$ fluent profile use nonexistent_profile`
$ fluent module list

`# Flow:
# 1. allOpts.profile = undefined
# 2. Active Profile: { activeProfile: 'nonexistent_profile' }
# 3. allOpts.profile = 'nonexistent_profile' (from Active Profile)
# 4. loadConfigs calls loadProfile('nonexistent_profile')
# 5. loadProfile checks if profile exists
# 6. Error: "Profile 'nonexistent_profile' does not exist. Use 'profile' command..."
# 7. process.exit(1)
`

Scenario 3: Active Profile exists, retailer required but missing

`$ fluent profile use apsear2dev  # No retailer set
`$ fluent setup payment-service-provider

`# Flow:
# 1. allOpts.profile = 'apsear2dev', allOpts.retailer = undefined
# 2. loadConfigs loads profile successfully
# 3. allOpts.retailer still undefined
# 4. config.retailer = {} (empty)
# 5. Task calls checkConfigForRetailerProfile(config)
# 6. Error: "Retailer must be set. Use --retailer flag or fluent profile use <profile> [-r|--retailer] <retailer>"
# 7. Throws error
`

Scenario 4: CLI flags override Active Profile

`$ fluent profile use apsear2dev --retailer ATEST2`
$ fluent module list --profile production --retailer PRODRETAILER

`# Flow:
# 1. allOpts.profile = 'production', allOpts.retailer = 'PRODRETAILER' (from CLI)
# 2. resolveDefaults sees CLI values exist
# 3. Skip Active Profile (CLI takes precedence)
# 4. Use 'production' and 'PRODRETAILER'
`

Task Option Changes

Before

`// packages/cli/src/tasks/module/moduleList.ts
export const taskdef: fluentCliTypes.Taskdef = {`
 command`: 'module',`
 subcommand`: 'list',`
 options`: [`
   {
     flags`: '-p, --profile <profile>',`
     description`: 'The Profile to use.',`
     required`: true  // ← Commander enforces this
`   }
 ],
 run`: async function (config, args, opts) {`
   checkConfigForAccountProfile(config);  `// ← Also validates
`   `// ...
` }
};

After

`// packages/cli/src/tasks/module/moduleList.ts
export const taskdef: fluentCliTypes.Taskdef = {`
 command`: 'module',`
 subcommand`: 'list',`
 options`: [`
   {
     flags`: '-p, --profile <profile>',`
     description`: 'The Profile to use. Defaults to active profile if set.',`
     required`: false  // ← Allow Commander to skip
`   }
 ],
 run`: async function (config, args, opts) {`
   checkConfigForAccountProfile(config);  `// ← This STILL validates!
`   `// ...
` }
};

Validation Utilities (Unchanged)

The existing validation utilities still work:
`// packages/cli/src/utils/validationSchemaUtil.ts
export const checkConfigForAccountProfile = (config: fluentCliTypes.Config): void => {`
 `if (!config.account) {`
   `throw new Error('Account profile not configured. Use --profile flag or set active profile with: fluent profile use <profile>');`
 }
};

`export const checkConfigForRetailerProfile = (config: fluentCliTypes.Config): void => {`
 checkConfigForAccountProfile(config);
 `if (!config.retailer || !config.retailer.id) {`
   `throw new Error('Retailer not configured. Use --retailer flag or set active profile with: fluent profile use <profile> [-r|--retailer] <retailer>');`
 }
};
These throw errors if `config.account` or `config.retailer` are missing, which happens when: - No active profile is set - Active profile doesn't have the needed value - loadProfile/loadRetailer failed to populate config

Configuration Flow Diagram

No alt provided

Implementation in configurationUtil.ts

`import activeContextUtil from './activeContextUtil.js';`

`const loadConfigs = (config: fluentCliTypes.Config, allOpts: OptionValues, modulePath: string | null) => {`
 log.debug('loadConfigs, allOpts: %s', allOpts);

 `// NEW: Inject active profile if CLI flags not provided
` `const defaults = activeContextUtil.resolveDefaults(allOpts);`

 `if (!allOpts.profile && defaults.profile) {`
   allOpts.profile `= defaults.profile;`
   log.debug('Using active profile: %s', defaults.profile);
 }

 `if (!allOpts.retailer && defaults.retailer) {`
   allOpts.retailer `= defaults.retailer;`
   log.debug('Using active retailer: %s', defaults.retailer);
 }

 `// EXISTING CODE (unchanged)
` `if (allOpts.profile) {`
   config.name `= allOpts.profile;`
   `const profileConfig = loadProfile(allOpts.profile);  // ← Validates & exits if bad
`   config.account `= _.merge(profileConfig);`
   `const retailerConfig = allOpts.retailer && !Array.isArray(allOpts.retailer)`
     `? loadRetailer(allOpts.profile, allOpts.retailer)  // ← Validates & exits if bad
`     `: {};`
   config.retailer `= _.merge(retailerConfig);`
 }

 `const moduleConfig = modulePath ? loadModule(modulePath, allOpts.retailer, allOpts.config) : {};`
 config.module `= _.merge(moduleConfig);`
 log.debug('loadConfigs: %o', config);
 `return config;`
};

Summary (Answer and Result)

The answer: Active Profile integrates seamlessly because:
  • ✅ We remove `required: true` from Commander option definitions
  • ✅ Active Profile populates `allOpts` BEFORE existing validation
  • ✅ Existing validation in `loadProfile()` and `loadRetailer()` is UNCHANGED
  • ✅ Existing validation in `checkConfigForAccountProfile()` is UNCHANGED
  • ✅ Tasks see no difference - they get `config.account` and `config.retailer` either way
Result: The system validates at the right place (where profile/retailer files are loaded), not at the wrong place (Commander option parsing). Active Profile just provides default values that flow through existing validation.

Related content

Fluent CLI Blueprints Guide
Edited 26 days ago
Learn to deploy and manage module collections using accelerator blueprints. Partners can rapidly configure environments with pre-tested "recipes," while businesses benefit from faster time-to-market and reduced risk through automated conflict prevention and smart versioning.Key Values:
  • Efficiency: Features "Smart Resume" and upgrade detection to skip identical modules.
  • Flexibility: Customise via selective installation (`--include`/`--exclude`).
  • Note: Semantic versioning is strictly enforced; downgrades require the `--force` flag.
Fluent CLI Reference (v2.x.x)
Edited 26 days ago
This guide covers Fluent CLI v2.x.x, the primary tool for managing Fluent Commerce accounts and assets. Implementing partners use it to automate environment setups and integrate workflows into CI/CD pipelines. For the business, the CLI ensures faster deployment cycles and high consistency, eliminating manual configuration overhead to scale retail operations with speed.Note: Requires Node.js >= 22.0.0. Profiles are stored locally in `~/.fluentcommerce/`; ensure sensitive credentials are protected according to your organization's security policies.
CLI Blueprint Troubleshooting Guide
Edited 138 days ago
What is a Blueprint?
Edited 26 days ago
This guide covers the blueprint lifecycle, from design to management, teaching you to deploy pre-configured module collections using the Fluent CLI. Implementing partners gain a consistent, repeatable setup across environments, while businesses benefit from faster deployments and reduced downtime via automated conflict prevention.Key features include Smart Versioning for automatic upgrades and Snapshot Mode for development testing. Note: Production requires exact versions; semver ranges are prohibited to ensure stability.
Marco Heuer

Marco Heuer

Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Fluent Logo