Blueprint Config Command
Essential knowledge
Intended Audience:
Technical User
Author:
Marco Heuer
Changed on:
20 Aug 2026
Overview
Master the`blueprint config` command to automatically generate JSON configuration files for every module in a blueprint. This article teaches implementing partners to prepare retailer-specific settings across multiple environments (dev, staging, prod) before installation.For the business, this ensures consistent environment setups and reduces deployment errors by pre-populating essential placeholders. Note: Generating configs requires retailer-level authentication. Existing files are skipped by default to protect custom edits unless you use the `--force` flag.Key points
- Purpose: Generates files named
`module.config.<RETAILER>.<module>.json`in your current directory, containing default settings and environment placeholders. - Smart Workflow: Use
`--module-path`to generate configs from locally downloaded modules—ideal for offline or air-gapped environments. - Environment Management: Easily create unique configs for different retailers using the
`-r`flag, allowing for seamless multi-environment tracking in Git. - Customization: Generated files should be reviewed and edited (e.g., adding integration endpoints) before running the
`blueprint install`command. - Safety: Use
`--force`only when you intend to overwrite existing configs; otherwise, the CLI skips them to preserve your manual customizations.
The
module.config.RETAILER01.custom-order-module.json
module.config.RETAILER01.payment-extension.json
Output:
info: Modules to process: 3
info: Processing module: acme/base-module v2.0.0
info: Config created: module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info: Config created: module.config.RETAILER01.custom-order-module.json
info: Processing module: mycompany/payment-extension v1.8.0
info: Config created: module.config.RETAILER01.payment-extension.json
info:
info: Summary
┌──────────────────────────────────────┬─────────┬────────────────────────────────────────────────────┐
│ module │ status │ file │
├──────────────────────────────────────┼─────────┼────────────────────────────────────────────────────┤
│ acme/base-module │ + Created│ module.config.RETAILER01.base-module.json │
│ acme/custom-order-module │ + Created│ module.config.RETAILER01.custom-order-module.json │
│ mycompany/payment-extension │ + Created│ module.config.RETAILER01.payment-extension.json │
└──────────────────────────────────────┴─────────┴────────────────────────────────────────────────────┘
info: + Created: 3
info: - Skipped: 0
info: [SUCCESS] (blueprintConfig) Generated config files for 3 modules (0 skipped, 0 errors)
Output:
info: Config already exists (use --force to overwrite): module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info: Config created: module.config.RETAILER01.custom-order-module.json
...
info: + Created: 1
info: - Skipped: 2
Output:
info: Overwriting existing config file
info: Config created: module.config.RETAILER01.base-module.json
-p myprofile \
-r RETAILER01 \
--base-dir /var/tmp/modules
Output:
info: Generating config files for blueprint: retail-order-management
info: Modules to process: 3
info: Processing module: acme/base-module v2.0.0
info: Using local module: acme-base-module-2.0.0.zip
info: Config created: module.config.RETAILER01.base-module.json
Benefits of local module path:
This creates retailer-specific configs:
module.config.STAGE01.base-module.json
module.config.PROD01.base-module.json
git commit -m "Add module configs for v1.0.0"
Generated config files contain:
"name": "acme/custom-order-module",
"version": "2.5.2",
"includeAssets": [],
"excludeAssets": [],
"assetFolder": "modules/custom-order-module",
"retailer": {
"ref": "RETAILER01",
"name": "Retailer Name"
},
"account": {
"id": 123,
"name": "Account Name"
},
"placeholders": {
"RETAILER_REF": "RETAILER01",
"ACCOUNT_ID": "123"
}
}
"name": "acme/custom-order-module",
"version": "2.5.2",
"includeAssets": [],
"excludeAssets": [],
"assetFolder": "modules/custom-order-module",
"retailer": {
"ref": "RETAILER01",
"name": "Retailer Name"
},
"account": {
"id": 123,
"name": "Account Name"
},
"placeholders": {
"RETAILER_REF": "RETAILER01",
"ACCOUNT_ID": "123"
}
}
jq . "$f" > /dev/null
Result: All configs created successfullyNext: Review and customise configs, then install
Result: Only missing config is regenerated
Result: All configs overwritten with new defaultsWarning: Custom edits will be lost - backup first!
Solutions:
Solution: Verify blueprint file path
Solutions:
Solutions:
`blueprint config` command generates module configuration files for all modules defined in a blueprint.Syntax
`fluent blueprint config <blueprint> [options]`Arguments
| Argument | Description | Required |
`<blueprint>` | Path to blueprint JSON file | Yes |
Options
| Option | Description | Required | Default |
`-p, --profile <profile>` | Profile to use | No | Current active profile |
`-r, --retailer <retailer>` | Retailer to use | No | Current active retailer |
`--base-dir <directory>` | Base directory for extracting modules | No | `/tmp` |
`-mp, --module-path <directory>` | Local directory containing downloaded modules. Overrides modulePath in blueprint. | No | None |
`-f, --force` | Overwrite existing config files | No | `false` |
Authentication
This command requires:- Retailer-level authentication - Must have valid retailer credentials
- Active profile with retailer - Profile must contain retailer settings
How it Works
For each module in the blueprint:- Prepare Module - Downloads module if needed (or uses local path) - Extracts to temporary directory - Reads module.json metadata
- Generate Config - Creates module config JSON file - Names file:
`module.config.<RETAILER>.<module-short-name>.json`- Populates with default settings and placeholders - Check Existing - If config already exists and
`--force`not used: skips and logs - If config exists and`--force`used: overwrites - Cleanup - Removes temporary extracted files - Keeps generated config files in current directory
Output
The command displays:- Processing status for each module
- Config file creation/skip status
- Summary statistics
- Final result table
Status Indicators
| Icon | Status | Meaning |
`+` | Created | Config file generated successfully |
`-` | Exists | Config already exists, skipped (no --force) |
`!` | Error | Failed to generate config |
Generated Files
Config files are created in the current working directory:`module.config.RETAILER01.base-module.json`module.config.RETAILER01.custom-order-module.json
module.config.RETAILER01.payment-extension.json
File Naming Pattern
`module.config.<RETAILER-REF>.<MODULE-SHORT-NAME>.json``RETAILER-REF`- Retailer reference code (e.g., RETAILER01)`MODULE-SHORT-NAME`- Extracted from module name (e.g., custom-order-module)
Usage Examples
Basic Usage
Generate configs for all modules:`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`Output:
`info: Generating config files for blueprint: retail-order-management`info: Modules to process: 3
info: Processing module: acme/base-module v2.0.0
info: Config created: module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info: Config created: module.config.RETAILER01.custom-order-module.json
info: Processing module: mycompany/payment-extension v1.8.0
info: Config created: module.config.RETAILER01.payment-extension.json
info:
info: Summary
┌──────────────────────────────────────┬─────────┬────────────────────────────────────────────────────┐
│ module │ status │ file │
├──────────────────────────────────────┼─────────┼────────────────────────────────────────────────────┤
│ acme/base-module │ + Created│ module.config.RETAILER01.base-module.json │
│ acme/custom-order-module │ + Created│ module.config.RETAILER01.custom-order-module.json │
│ mycompany/payment-extension │ + Created│ module.config.RETAILER01.payment-extension.json │
└──────────────────────────────────────┴─────────┴────────────────────────────────────────────────────┘
info: + Created: 3
info: - Skipped: 0
info: [SUCCESS] (blueprintConfig) Generated config files for 3 modules (0 skipped, 0 errors)
Skip Existing Configs
Without`--force`, existing configs are skipped:`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`Output:
`info: Processing module: acme/base-module v2.0.0`info: Config already exists (use --force to overwrite): module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info: Config created: module.config.RETAILER01.custom-order-module.json
...
info: + Created: 1
info: - Skipped: 2
Force Overwrite
Regenerate all configs, overwriting existing:`fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --force`Output:
`info: Processing module: acme/base-module v2.0.0`info: Overwriting existing config file
info: Config created: module.config.RETAILER01.base-module.json
Custom Base Directory
Use custom directory for module extraction:`fluent blueprint config accelerator.json \`-p myprofile \
-r RETAILER01 \
--base-dir /var/tmp/modules
Generate from Local Modules
Generate configs from locally downloaded modules instead of downloading them:`# Step 1: Download all modules to local directory
`fluent blueprint download accelerator.json -o ./modules`# Step 2: Generate configs from local directory
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --module-path ./modulesOutput:
`info: Using local module path: /path/to/modules`info: Generating config files for blueprint: retail-order-management
info: Modules to process: 3
info: Processing module: acme/base-module v2.0.0
info: Using local module: acme-base-module-2.0.0.zip
info: Config created: module.config.RETAILER01.base-module.json
Benefits of local module path:
- Offline capability - Generate configs without internet connection
- Faster processing - No download time
- Version control - Keep specific module versions locally
- Air-gapped environments - Work in restricted networks
- Consistency - Same modules across multiple config generations
- Module filenames must match the pattern:
`<module-name-with-dashes>-<version>.zip` - Example:
`acme-base-module-2.0.0.zip` - Slashes in module names are replaced with dashes
- If
`--module-path`is specified, it overrides any`modulePath`in the blueprint - The directory must exist and contain all required module archives
- Missing modules will cause config generation to fail for that module
Different Retailer Per Environment
Generate configs for multiple environments:`# Development environment
`fluent blueprint config accelerator.json -p dev -r DEV01`# Staging environment
`fluent blueprint config accelerator.json -p staging -r STAGE01`# Production environment
`fluent blueprint config accelerator.json -p prod -r PROD01This creates retailer-specific configs:
`module.config.DEV01.base-module.json`module.config.STAGE01.base-module.json
module.config.PROD01.base-module.json
Use Cases
Pre-Installation Configuration
Generate and customise configs before installation:`# Step 1: Generate default configs
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`# Step 2: Review and edit configs
`vi module.config.RETAILER01.*.json`# Step 3: Install with custom configs
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01Offline Workflow with Local Modules
Download modules once, then generate configs and install offline:`# Step 1: Download all modules to local directory (requires internet)
`fluent blueprint download accelerator.json -o ./modules`# Step 2: Generate configs from local modules (offline)
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --module-path ./modules`# Step 3: Review and customise configs
`vi module.config.RETAILER01.*.json`# Step 4: Install from local modules (offline)
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --module-path ./modulesMulti-Environment Setup
Create configs for all environments:`# Generate for dev
`fluent blueprint config blueprint.json -p dev -r DEV`# Generate for staging
`fluent blueprint config blueprint.json -p staging -r STAGE`# Generate for production
`fluent blueprint config blueprint.json -p prod -r PROD`# Customise per environment
# Edit each set of configs with environment-specific values
`Config Version Control
Track config changes in git:`# Generate configs
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`# Add to git
`git add module.config.*.jsongit commit -m "Add module configs for v1.0.0"
`# Update blueprint to v2.0.0
`fluent blueprint config accelerator-v2.json -p myprofile -r RETAILER01 --force`# Review changes
`git diff module.config.*.jsonSelective Config Generation
Generate config for specific module subset:`# Create custom blueprint with subset of modules
`jq '.modules = [.modules[0], .modules[2]]' full-blueprint.json > subset.json`# Generate configs only for those modules
`fluent blueprint config subset.json -p myprofile -r RETAILER01Generated config files contain:
`{`"name": "acme/custom-order-module",
"version": "2.5.2",
"includeAssets": [],
"excludeAssets": [],
"assetFolder": "modules/custom-order-module",
"retailer": {
"ref": "RETAILER01",
"name": "Retailer Name"
},
"account": {
"id": 123,
"name": "Account Name"
},
"placeholders": {
"RETAILER_REF": "RETAILER01",
"ACCOUNT_ID": "123"
}
}
Config File Structure
Generated config files contain:`{`"name": "acme/custom-order-module",
"version": "2.5.2",
"includeAssets": [],
"excludeAssets": [],
"assetFolder": "modules/custom-order-module",
"retailer": {
"ref": "RETAILER01",
"name": "Retailer Name"
},
"account": {
"id": 123,
"name": "Account Name"
},
"placeholders": {
"RETAILER_REF": "RETAILER01",
"ACCOUNT_ID": "123"
}
}
Key Fields
- name - Module identifier
- version - Module version
- includeAssets - Assets to include (if specified in blueprint)
- excludeAssets - Assets to exclude (if specified in blueprint)
- retailer - Retailer information from profile
- account - Account information from profile
- placeholders - Key-value pairs for variable substitution
Post Generation Steps
1. Review Configs
`# List generated configs
`ls -la module.config.*.json`# Review a config
`cat module.config.RETAILER01.custom-order-module.json | jq .2. Customise Settings
Edit configs to add:- Environment-specific values
- Custom placeholders
- Asset filters
- Integration endpoints
3. Validate Configs
`# Check JSON syntax
for f in module.config.*.json; do
` echo "Validating $f"jq . "$f" > /dev/null
`&& echo "+ Valid" || echo "! Invalid"``done
`4. Backup Configs
`# Create backup before installation
`tar czf configs-backup-`$(date +%Y%m%d).tar.gz module.config.*.json`Common Scenarios
Scenario 1: Fresh Setup
Situation: First time generating configs`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`Result: All configs created successfullyNext: Review and customise configs, then install
Scenario 2: Regenerate One Config
Situation: Need to regenerate single module config`# Delete the config
`rm module.config.RETAILER01.custom-order-module.json`# Regenerate all (only missing one will be created)
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01Result: Only missing config is regenerated
Scenario 3: Update All Configs
Situation: Blueprint updated, need fresh configs`fluent blueprint config accelerator-v2.json -p myprofile -r RETAILER01 --force`Result: All configs overwritten with new defaultsWarning: Custom edits will be lost - backup first!
Error Handling
Module Download Failed
Error:`error: Failed to prepare module: acme/custom-order-module`Solutions:
- Check network connectivity
- Verify module exists in repository
- Check module version is valid
- Try with
`--base-dir`to use different temp location
Invalid Blueprint
Error:`error: Blueprint file not found: accelerator.json`Solution: Verify blueprint file path
Missing Authentication
Error:`error: Retailer configuration required`Solutions:
- Specify retailer:
`-r RETAILER01` - Set active retailer:
`fluent profile use myprofile -r RETAILER01` - Check profile:
`fluent profile list`
Permission Denied
Error:`error: EACCES: permission denied, open 'module.config.RETAILER01.base-module.json'`Solutions:
- Check write permissions in current directory
- Run from writable directory
- Check disk space
Best Practices
Before Generation
- Validate blueprint with
`validate`command - Review blueprint with
`describe`command - Check existing configs to avoid accidental overwrites
- Backup current configs if regenerating
- Ensure correct profile/retailer for target environment
After Generation
- Validate JSON syntax of all configs
- Review placeholder values for correctness
- Customise per environment as needed
- Test in non-production first
- Version control configs for tracking changes
Multi-Environment
- Use consistent naming for environments (dev, staging, prod)
- Separate configs by retailer reference
- Document customisations in comments or README
- Automate config generation in CI/CD pipelines
Related Commands
- Blueprint validate - Validate blueprint before generating configs
- Blueprint describe - Preview blueprint before generating configs
- Blueprint install - Install using generated configs
- Module config - Generate single module config
