Blueprint Install Command
Essential knowledge
Intended Audience:
Technical User
Author:
Marco Heuer
Changed on:
20 Aug 2026
Overview
The`blueprint install` command is the engine of the Fluent Commerce Accelerator, enabling sequential installation of module collections. Partner developers gain reliable, repeatable deployments, while the business achieves operational stability and faster disaster recovery.Its built-in logic ensures safe production updates by automatically handling upgrades while blocking risky downgrades without explicit confirmation. This prevents accidental data or logic loss, resolving the pain point of manual configuration errors. Note: Installations require retailer-level authentication.Key points
- Smart Resume & Versioning: The CLI automatically skips identical versions and resumes failed installations from the point of failure. Upgrades are automatic, but downgrades and reinstalls (same version) require the
`--force`flag. - Selective Deployment: Use
`--include`or`--exclude`to install specific subsets of a blueprint—perfect for phased rollouts or excluding test data from production. - Safety First: The command performs a "Pre-Flight Check" that validates blueprint structure and checks for incompatible conflicts before making any changes.
- Snapshot Mode: Perfect for development, this mode resolves
`SNAPSHOT`or 4-part build versions (e.g.,`2.5.0.125`) to ensure you are always testing the latest code. - Offline/Air-Gapped Support: By using
`--module-path`, you can install modules directly from a local directory, bypassing the need for an internet connection. - Dry Run: Use
`--dry-run`to simulate the installation. This validates the blueprint and checks for conflicts without actually modifying the account.
The
Behaviour: Automatically installs the newer version without requiring
(Use --force to reinstall)
Behaviour:
(Use --force to downgrade)
Behaviour:
Result: Installs all 5 modules at v1.0.0Updated Blueprint (Blueprint v1.1) - Only 2 modules updated:
"modules": [
{ "name": "core", "version": "1.0.0" },
}
Running the Update:
Output:
- Module core v1.0.0 is already installed - skipping
Module 2/5: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Module 3/5: inventory
- Module inventory v1.0.0 is already installed - skipping
Module 4/5: payment
+ Upgrading module payment: v1.0.0 → v1.1.0
+ Module payment installed successfully
Module 5/5: shipping
- Module shipping v1.0.0 is already installed - skipping
Summary:
+ Installed: 2
- Skipped: 3
Result: Only the 2 upgraded modules (order, payment) were reinstalled!
Use Cases:
Module 1/3: core
+ Module core installed successfully
Module 2/3: order
+ Module order installed successfully
Module 3/3: inventory
+ Module inventory installed successfully
Summary:
+ Installed: 3
- Skipped: 0
Use Cases:
Module 1/8: core
+ Module core installed successfully
...
Output:
Module 1/1: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Summary:
+ Installed: 1
- Skipped: 0
Loaded blueprint: retail-order-management v1.0.0
Modules to install: 5
Validating blueprint...
Blueprint validation passed
Note: For detailed validation rules and standalone validation, see blueprint validate command.
Found 12 installed modules
No conflicts detected
Resolving: acme/base-module 2.0.0
→ Will resolve: 2.0.0
With Snapshot Flag:
Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0.125
→ Using custom path: s3://my-bucket/modules/
═══════════════════════════════════════════════
Module 1/5: acme/base-module
═══════════════════════════════════════════════
- Module acme/base-module v2.0.0 is already installed - skipping
(Use --force to reinstall)
═══════════════════════════════════════════════
Module 2/5: acme/custom-order-module
═══════════════════════════════════════════════
Preparing module: acme/custom-order-module
+ Module acme/custom-order-module installed successfully
Blueprint installation complete!
═══════════════════════════════════════════════
Blueprint: retail-order-management v1.0.0
Summary:
+ Installed: 3
- Skipped: 2
Output (second run):
- Module core is already installed - skipping
Module 2/10: order
- Module order is already installed - skipping
Module 3/10: payment
- Module payment is already installed - skipping
Module 4/10: shipping
- Module shipping is already installed - skipping
Module 5/10: inventory
Preparing module: inventory
+ Module inventory installed successfully
...
Output:
! Module core v2.0.0 is already installed - reinstalling due to --force flag
Preparing module: core
+ Module core installed successfully
Output:
Loaded blueprint: retail-order-management v1.0.0
Validating blueprint...
Blueprint validation passed
Checking for conflicts...
No conflicts detected
Dry-run mode: blueprint validation passed, no conflicts detected. Installation would proceed.
Output:
Loaded blueprint: retail-order-management v1.0.0
Validating blueprint...
Blueprint validation passed
Using local module path: /path/to/modules
═══════════════════════════════════════════════
Module 1/3: acme/base-module
═══════════════════════════════════════════════
Using local module: acme-base-module-2.0.0.zip
Preparing module: acme-base-module-2.0.0
+ Module acme/base-module installed successfully
Benefits of local installation:
Output:
Module 1/2: core
+ Module core installed successfully
Module 2/2: order
+ Module order installed successfully
Summary:
+ Installed: 2
- Skipped: 0
Output:
Module 1/8: core
+ Module core installed successfully
...
Summary:
+ Installed: 8
- Skipped: 0
Output:
- Module core v1.0.0 is already installed - skipping
Module 2/2: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Summary:
+ Installed: 1
- Skipped: 1
Result: Only the upgraded module (order) was reinstalled! No --force needed.
Output (without --force):
- Module order v1.1.0 is newer than blueprint version v1.0.0 - skipping downgrade
(Use --force to downgrade)
With --force:
Output:
- Downgrading module order: v1.1.0 → v1.0.0 (--force)
+ Module order installed successfully
The install command auto-discovers config files:
"name": "development-accelerator",
"version": "1.0.0",
"modules": [
{
"name": "acme/custom-order-module",
"version": "2.5.0",
"modulePath": "s3://my-dev-bucket/modules/",
"snapshot":
]
}
Installation:
Output:
Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0.125
→ Using custom path: s3://my-dev-bucket/modules/
Installing 1 modules...
Module 1/1: acme/custom-order-module
Using local module: acme-custom-order-module-2.5.0.125.zip
+ Module acme/custom-order-module installed successfully
File System Example:You can also use snapshot mode with local file system paths:
"name": "local-development-accelerator",
"version": "1.0.0",
"modules": [
{
"name": "acme/custom-order-module",
"version": "2.5.0",
"modulePath": "/local/modules/",
"snapshot":
]
}
Installation:
Output:
Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0-SNAPSHOT
→ Using local path: /local/modules/
Installing 1 modules...
Module 1/1: acme/custom-order-module
Using local module: acme-custom-order-module-2.5.0-SNAPSHOT.zip
+ Module acme/custom-order-module installed successfully
Use Cases:
"conflicts": [
{
"name": "legacy-order-module",
"type": "module",
"version": "*",
"reason": "Replaced by custom-order-module"
}
]
}
If conflict found:
error: - legacy-order-module v1.5.0 (module): Replaced by custom-order-module
Exit code: 2
Note: Reference modules (
Result: All 10 modules installed
+ Installed: 10
- Skipped: 0
Result: Modules 1-5 skipped, resumes from 6
+ Installed: 5
- Skipped: 5
Result: Skips 1-3, installs 4-10
+ Installed: 7
- Skipped: 3
Result: All modules reinstalled with new versions
+ Installed: 10
- Skipped: 0
fluent blueprint install accelerator.json -p prod -r PROD01
Behaviour:
error: - legacy-module v1.0.0 (module): Incompatible with new architecture
Resolution:
Solutions:
error: [INVALID_VERSION] Module version "abc" is not valid semver
error: Field: modules[2].version
Solution: Fix blueprint file and retry. For detailed validation rules, see blueprint validate.
"modules": [
{ "name": "core", "version": "1.0.0" },
}Important: Order dependencies by placing prerequisite modules first!
`blueprint install` command installs all modules defined in a blueprint sequentially.Key Features
- Smart Resume - Automatically skips already-installed modules, enabling seamless recovery from interruptions
- Smart Version Comparison - Intelligently handles upgrades (auto-allowed), same versions (skipped), and downgrades (requires --force)
- Selective Installation - Install only specific modules or exclude modules using
`--include`and`--exclude`flags - Conflict Detection - Validates blueprint-defined conflicts before installation begins
- Snapshot/Build Resolution - Automatically resolves latest development (SNAPSHOT) or RC build versions (4-part versions)
- Local Module Support - Install from locally downloaded modules for offline or air-gapped environments
- Dry-Run Validation - Test blueprint validation and conflict detection without installing modules
Syntax
`fluent blueprint install <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 |
`-w, --wait <millisecs>` | Wait time between tasks | No | `1000` |
`-bd, --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 |
`-i, --include <names>` | Comma-separated list of module names to install (installs only these modules from blueprint) | No | All modules |
`-e, --exclude <names>` | Comma-separated list of module names to exclude from installation | No | None |
`-f, --force` | Force reinstallation of modules with same version, and allow downgrades | No | `false` |
`--dry-run` | Validate without installing | No | `false` |
Authentication
This command requires:- Retailer-level authentication - Must have valid retailer credentials
- Active profile with retailer - Profile must contain retailer settings
Smart Resume Feature
The command automatically skips already-installed modules, enabling:- Resume interrupted installations - Just re-run the same command
- No manual tracking needed - Automatic detection of installed modules
- Safe by default - Won't reinstall unless
`--force`specified - Clear progress reporting - Shows installed, skipped, and failed counts
How It Works
For each module in the blueprint:- Pre-Flight Check (before installation loop)
- Validates blueprint structure
- Checks blueprint-defined conflicts
- Authenticates with Fluent API
- Queries installed modules
- Per-Module Version Check (during installation)
- Checks if module already installed
- Compares installed version with blueprint version
- Upgrade (newer version): Installs automatically
- Same version: Skips (or reinstalls with
`--force`) - Downgrade (older version): Skips (requires
`--force`) - If not installed: install normally
- Dual-Layer Detection
- First layer: Settings-based check (fast)
- Second layer: Actions log check (authoritative) - Catches module name variations
Smart Version Comparison
The command intelligently compares module versions using semantic versioning (semver) to determine the appropriate action:Upgrade Detection (Auto-Install)
When blueprint specifies a newer version than installed:`+ Upgrading module labs-module-common: v1.0.0 → v1.1.0`Behaviour: Automatically installs the newer version without requiring
`--force`Use Case: Blueprint updates with improved versionsSame Version (Skip or Reinstall)
When blueprint specifies the same version as installed:`- Module labs-module-common v1.0.0 is already installed - skipping`(Use --force to reinstall)
Behaviour:
- Without --force: Skips installation
- With --force: Reinstalls the same version
Downgrade Detection (Requires --force)
When blueprint specifies an older version than installed:`- Module labs-module-common v1.1.0 is newer than blueprint version v1.0.0 - skipping downgrade`(Use --force to downgrade)
Behaviour:
- Without --force: Skips installation with warning
- With --force: Downgrades to older version
Benefits
✅ Efficient Updates: Only changed modules are reinstalled in updated blueprints ✅ Safe Defaults: Upgrades are automatic, downgrades require explicit confirmation ✅ Clear Feedback: Visual indicators show exact action being taken ✅ Resume Support: Interrupted upgrades resume automaticallyExample: Blueprint Update Scenario
Initial Installation (Blueprint v1.0):`fluent blueprint install retail-v1.json -p myprofile -r RETAILER01`Result: Installs all 5 modules at v1.0.0Updated Blueprint (Blueprint v1.1) - Only 2 modules updated:
`{`"modules": [
{ "name": "core", "version": "1.0.0" },
`// ← Unchanged
` { "name": "order", "version": "1.1.0" }, `// ← Upgraded
` { "name": "inventory", "version": "1.0.0" }, `// ← Unchanged
` { "name": "payment", "version": "1.1.0" }, `// ← Upgraded
` { "name": "shipping", "version": "1.0.0" } `// ← Unchanged
` ]}
Running the Update:
`fluent blueprint install retail-v1.1.json -p myprofile -r RETAILER01`Output:
`Module 1/5: core`- Module core v1.0.0 is already installed - skipping
Module 2/5: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Module 3/5: inventory
- Module inventory v1.0.0 is already installed - skipping
Module 4/5: payment
+ Upgrading module payment: v1.0.0 → v1.1.0
+ Module payment installed successfully
Module 5/5: shipping
- Module shipping v1.0.0 is already installed - skipping
Summary:
+ Installed: 2
- Skipped: 3
Result: Only the 2 upgraded modules (order, payment) were reinstalled!
Selective Module Installation
Install specific modules from a blueprint using include/exclude filters, following the same pattern as`module install` command.Include Specific Modules
Install only specified modules from the blueprint:`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --include "core,order,inventory"`Use Cases:
- Incremental rollout: Install modules one at a time
- Testing: Test specific modules before full deployment
- Partial installation: Install only required modules for a feature
- Debugging: Install only the problematic module
`Filtered to 3 modules (from 10 total): core, order, inventory`Module 1/3: core
+ Module core installed successfully
Module 2/3: order
+ Module order installed successfully
Module 3/3: inventory
+ Module inventory installed successfully
Summary:
+ Installed: 3
- Skipped: 0
Exclude Specific Modules
Install all except specified modules from the blueprint:`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --exclude "test-module,demo-data"`Use Cases:
- Production deployment: Exclude test/demo modules
- Selective skipping: Skip known problematic modules
- Phased rollout: Exclude modules for later installation
- Resource constraints: Skip optional modules
`Excluded 2 modules (8 remaining)`Module 1/8: core
+ Module core installed successfully
...
Validation
Mutually Exclusive: Cannot use`--include` and `--exclude` together:`fluent blueprint install accelerator.json --include "core" --exclude "test"``# Error: Cannot use --include and --exclude together. Use one or the other.
`Non-Existent Modules: Warning if specified module not found:`fluent blueprint install accelerator.json --include "core,nonexistent,order"``# Warning: Module names not found in blueprint: nonexistent
# Filtered to 2 modules (from 10 total): core, order
`No Matches: Error if filter excludes all modules:`fluent blueprint install accelerator.json --include "nonexistent"``# Error: No modules matched include filter: nonexistent
`Consistency with Module Install
The`--include` and `--exclude` options follow the same pattern as `module install`:| Command | Include Flag | Exclude Flag |
`module install` | `-i, --include <assets...>` | `-e, --exclude <assets...>` |
`blueprint install` | `-i, --include <names>` | `-e, --exclude <names>` |
Combined with Smart Version Comparison
Selective installation works seamlessly with version comparison:`# Install only the "order" module, upgrade if newer version
`fluent blueprint install retail-v1.1.json -p myprofile -r RETAILER01 --include "order"Output:
`Filtered to 1 modules (from 5 total): order`Module 1/1: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Summary:
+ Installed: 1
- Skipped: 0
`
`Installation Flow
`
Phase 1: Validation
`Loading blueprint from: accelerator.json`Loaded blueprint: retail-order-management v1.0.0
Modules to install: 5
Validating blueprint...
Blueprint validation passed
Note: For detailed validation rules and standalone validation, see blueprint validate command.
Phase 2: Conflict Detection
`Checking for conflicts...`Found 12 installed modules
No conflicts detected
Phase 3: Module Resolution
`Resolving module versions...`Resolving: acme/base-module 2.0.0
→ Will resolve: 2.0.0
With Snapshot Flag:
`Resolving module versions...`Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0.125
→ Using custom path: s3://my-bucket/modules/
Phase 4: Sequential Installation
`Installing 5 modules...`═══════════════════════════════════════════════
Module 1/5: acme/base-module
═══════════════════════════════════════════════
- Module acme/base-module v2.0.0 is already installed - skipping
(Use --force to reinstall)
═══════════════════════════════════════════════
Module 2/5: acme/custom-order-module
═══════════════════════════════════════════════
Preparing module: acme/custom-order-module
+ Module acme/custom-order-module installed successfully
Phase 5: Summary
`═══════════════════════════════════════════════`Blueprint installation complete!
═══════════════════════════════════════════════
Blueprint: retail-order-management v1.0.0
Summary:
+ Installed: 3
- Skipped: 2
Status Indicators
| Icon | Status | Meaning |
`+` | Installed | Module installed successfully |
`-` | Skipped | Module already installed, skipped |
`+` | Upgrading | Installing newer version (auto-allowed) |
`-` | Downgrading | Installing older version (requires --force) |
`!` | Reinstalling | Module exists but forcing reinstall (same version) |
`!` | Failed | Installation failed, stopping |
Usage Examples
Basic Installation
Install all modules:`fluent blueprint install accelerator.json -p myprofile -r RETAILER01`Resume Interrupted Installation
Installation failed on module 5 of 10:`# First attempt - fails on module 5
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01`# Error occurs...
# Just re-run the same command - modules 1-4 automatically skipped
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01Output (second run):
`Module 1/10: core`- Module core is already installed - skipping
Module 2/10: order
- Module order is already installed - skipping
Module 3/10: payment
- Module payment is already installed - skipping
Module 4/10: shipping
- Module shipping is already installed - skipping
Module 5/10: inventory
Preparing module: inventory
+ Module inventory installed successfully
...
Force Reinstall
Reinstall all modules even if already installed:`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force`Output:
`Module 1/5: core`! Module core v2.0.0 is already installed - reinstalling due to --force flag
Preparing module: core
+ Module core installed successfully
Dry Run Validation
Validate without installing:`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --dry-run`Output:
`Loading blueprint from: accelerator.json`Loaded blueprint: retail-order-management v1.0.0
Validating blueprint...
Blueprint validation passed
Checking for conflicts...
No conflicts detected
Dry-run mode: blueprint validation passed, no conflicts detected. Installation would proceed.
Custom Wait Time
Add delay between module installations:`# Wait 5 seconds between modules
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --wait 5000Install from Local Modules
Install from locally downloaded modules instead of downloading from remote sources:`# Step 1: Download all modules to local directory
`fluent blueprint download accelerator.json -o ./modules`# Step 2: Install from local directory
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --module-path ./modulesOutput:
`Loading blueprint from: accelerator.json`Loaded blueprint: retail-order-management v1.0.0
Validating blueprint...
Blueprint validation passed
Using local module path: /path/to/modules
═══════════════════════════════════════════════
Module 1/3: acme/base-module
═══════════════════════════════════════════════
Using local module: acme-base-module-2.0.0.zip
Preparing module: acme-base-module-2.0.0
+ Module acme/base-module installed successfully
Benefits of local installation:
- Offline capability - Install without internet connection
- Faster installation - No download time
- Version control - Keep specific module versions locally
- Air-gapped environments - Deploy to restricted networks
- Consistency - Same modules across multiple installations
`<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 installation to failInstall Only Specific Modules
Install selected modules from a blueprint:`# Install only core and order modules
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --include "core,order"Output:
`Filtered to 2 modules (from 10 total): core, order`Module 1/2: core
+ Module core installed successfully
Module 2/2: order
+ Module order installed successfully
Summary:
+ Installed: 2
- Skipped: 0
Exclude Specific Modules
Install all modules except specified ones:`# Install all except test and demo modules
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --exclude "test-module,demo-data"Output:
`Excluded 2 modules (8 remaining)`Module 1/8: core
+ Module core installed successfully
...
Summary:
+ Installed: 8
- Skipped: 0
Upgrade Modules with New Blueprint Version
Install updated blueprint - only upgraded modules are reinstalled:`# Original blueprint has core v1.0.0, order v1.0.0
`fluent blueprint install retail-v1.0.json -p myprofile -r RETAILER01`# Updated blueprint has core v1.0.0, order v1.1.0 (upgraded!)
`fluent blueprint install retail-v1.1.json -p myprofile -r RETAILER01Output:
`Module 1/2: core`- Module core v1.0.0 is already installed - skipping
Module 2/2: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
Summary:
+ Installed: 1
- Skipped: 1
Result: Only the upgraded module (order) was reinstalled! No --force needed.
Force Downgrade to Older Version
Downgrade requires explicit --force flag:`# Currently have order v1.1.0 installed
# Blueprint specifies order v1.0.0 (older)
`fluent blueprint install retail-v1.0.json -p myprofile -r RETAILER01Output (without --force):
`Module 1/2: order`- Module order v1.1.0 is newer than blueprint version v1.0.0 - skipping downgrade
(Use --force to downgrade)
With --force:
`fluent blueprint install retail-v1.0.json -p myprofile -r RETAILER01 --force`Output:
`Module 1/2: order`- Downgrading module order: v1.1.0 → v1.0.0 (--force)
+ Module order installed successfully
Use Pre-Generated Configs
Install with custom configs created earlier:`# Step 1: Generate and customise configs
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01`# Edit configs as needed...
``# Step 2: Install with custom configs
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01The install command auto-discovers config files:
- Looks for:
`module.config.<RETAILER>.<module-short-name>.json` - Uses custom configs if found
- Generates defaults if not found
Use Snapshot Mode for Development
Install latest development builds automatically using the`snapshot` flag:Blueprint with Snapshot:`{`"name": "development-accelerator",
"version": "1.0.0",
"modules": [
{
"name": "acme/custom-order-module",
"version": "2.5.0",
"modulePath": "s3://my-dev-bucket/modules/",
"snapshot":
`true
` }]
}
Installation:
`fluent blueprint install dev-accelerator.json -p myprofile -r DEV01`Output:
`Resolving module versions...`Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0.125
→ Using custom path: s3://my-dev-bucket/modules/
Installing 1 modules...
Module 1/1: acme/custom-order-module
Using local module: acme-custom-order-module-2.5.0.125.zip
+ Module acme/custom-order-module installed successfully
File System Example:You can also use snapshot mode with local file system paths:
`{`"name": "local-development-accelerator",
"version": "1.0.0",
"modules": [
{
"name": "acme/custom-order-module",
"version": "2.5.0",
"modulePath": "/local/modules/",
"snapshot":
`true
` }]
}
Installation:
`fluent blueprint install local-dev-accelerator.json -p myprofile -r DEV01`Output:
`Resolving module versions...`Resolving: acme/custom-order-module 2.5.0
→ Snapshot mode enabled, resolving latest snapshot/build version...
→ Resolved snapshot version: 2.5.0-SNAPSHOT
→ Using local path: /local/modules/
Installing 1 modules...
Module 1/1: acme/custom-order-module
Using local module: acme-custom-order-module-2.5.0-SNAPSHOT.zip
+ Module acme/custom-order-module installed successfully
Use Cases:
- Development Environments: Always use latest build without updating blueprint
- Release Candidates: Test latest RC builds marked as SNAPSHOT
- Build Pipelines: Automatically pick up newest builds by build number (4-part versions)
- Integration Testing: Ensure tests run against latest development version
- Offline Development: Work with locally built modules without network access
- Requires S3 or file system module path (
`modulePath: "s3://..."`or`/local/path/`) - Version must be exact (e.g.,
`"2.5.0"`) - Looks for
`2.5.0-SNAPSHOT`or`2.5.0.XXX`(4-part version) - Will NOT use exact release version
`2.5.0` - Fails if no snapshot/build versions found
Conflict Detection
Blueprint-Defined Conflicts
Blocks installation if conflicts detected:`{`"conflicts": [
{
"name": "legacy-order-module",
"type": "module",
"version": "*",
"reason": "Replaced by custom-order-module"
}
]
}
If conflict found:
`error: Installation blocked due to conflicts:`error: - legacy-order-module v1.5.0 (module): Replaced by custom-order-module
Exit code: 2
Duplicate Detection (Without --force)
Old behaviour (before smart resume):- Checked ALL modules upfront
- If ANY module installed: blocked entire installation - Exit code 2
- Checks each module individually
- Skips installed modules
- Continues with remaining modules
- Exit code 0 (unless actual error)
Module Name Matching
The command handles various module name formats:| Blueprint References | Installed As | Match? | Notes |
`core` | `fluent-commerce/core` | Yes | Reference module shorthand |
`order` | `fluent-commerce/order` | Yes | Reference module shorthand |
`acme/custom-order-module` | `acme/custom-order-module` | Yes | Namespaced module |
`my-custom-module` | `my-custom-module` | Yes | Custom module |
`core`, `order`, `inventory`, `fulfilment`) can be specified using shorthand names in blueprints. See Module Types for details.Both settings and actions log are checked for maximum compatibility.Use Cases
Scenario 1: Fresh Installation
Situation: Installing blueprint on new account`fluent blueprint install accelerator.json -p myprofile -r RETAILER01`Result: All 10 modules installed
`Summary:`+ Installed: 10
- Skipped: 0
Scenario 2: Network Interruption
Situation: Installation fails on module 6 due to network error`# First attempt
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01`# Error: Network timeout on module 6
``# Fix network, re-run same command
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01Result: Modules 1-5 skipped, resumes from 6
`Summary:`+ Installed: 5
- Skipped: 5
Scenario 3: Partial Existing Installation
Situation: Some modules already installed manually`# Modules 1-3 already installed
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01Result: Skips 1-3, installs 4-10
`Summary:`+ Installed: 7
- Skipped: 3
Scenario 4: Blueprint Update
Situation: Upgrading blueprint from v1 to v2`# Install v2 with --force to upgrade existing modules
`fluent blueprint install accelerator-v2.json -p myprofile -r RETAILER01 --forceResult: All modules reinstalled with new versions
`Summary:`+ Installed: 10
- Skipped: 0
Scenario 5: Multi-Environment Rollout
Situation: Installing same blueprint across environments`# Development
`fluent blueprint install accelerator.json -p dev -r DEV01`# Staging
`fluent blueprint install accelerator.json -p staging -r STAGE01`# Production (with validation)
`fluent blueprint install accelerator.json -p prod -r PROD01 --dry-runfluent blueprint install accelerator.json -p prod -r PROD01
Error Handling
Module Installation Failed
Error:`error: ! Failed to install module custom-order-module: Module validation failed`Behaviour:
- Installation stops immediately
- Exit code 3
- Already installed modules remain
- Fix the issue (e.g., update config file)
- Re-run same command
- Already-installed modules skipped automatically
Conflict Detected
Error:`error: Installation blocked due to conflicts:`error: - legacy-module v1.0.0 (module): Incompatible with new architecture
Resolution:
- Remove conflicting module first
- Or remove conflict definition from blueprint (if safe)
- Re-run installation
Authentication Failed
Error:`error: Authentication failed for account`Solutions:
- Verify profile credentials:
`fluent profile list` - Update profile:
`fluent profile update myprofile` - Check network connectivity
Blueprint Validation Failed
Error:`error: Blueprint validation failed:`error: [INVALID_VERSION] Module version "abc" is not valid semver
error: Field: modules[2].version
Solution: Fix blueprint file and retry. For detailed validation rules, see blueprint validate.
Performance Consideration
Sequential Installation
- Modules installed one at a time (not parallel)
- Allows proper dependency resolution
- Prevents race conditions
- Wait time configurable with
`--wait`
Network Efficiency
- Smart resume avoids re-downloading installed modules
- Failed downloads cleaned up automatically
- Temp files removed after each module
Progress Tracking
- Real-time status updates per module
- Summary statistics at end
- Clear indication of remaining work
Best Practices
Before Installation
- Validate blueprint: Use
`blueprint validate`for comprehensive validation - Preview blueprint: Use
`blueprint describe`to review contents - Check conflicts: Review conflict rules
- Generate configs: Use
`blueprint config`first - Dry run: Test with
`--dry-run`flag - Backup: Document current module versions
During Installation
- Monitor progress: Watch for skipped/failed modules
- Keep terminal open: Don't interrupt unless necessary
- Check logs: Review output for warnings
- Note failures: Document which module failed for recovery
After Installation
- Verify success: Check summary statistics
- Test functionality: Validate module features work
- Document versions: Record what was installed
- Clean up: Remove temporary files if needed
Multi-Environment
- Test in lower environments first (dev → staging → prod)
- Use same blueprint file for consistency
- Different configs per environment for customisation
- Validate before prod with
`--dry-run`
Exit Codes
| Code | Meaning | Recovery |
| 0 | Success - all modules installed or skipped | None needed |
| 1 | Blueprint file not found | Check file path |
| 2 | Conflicts detected | Resolve conflicts, retry |
| 3 | Module installation failed | Fix issue, re-run (auto-resumes) |
Module Installation Order
Modules are installed in the order defined in the blueprint:`{`"modules": [
{ "name": "core", "version": "1.0.0" },
`// ← Installed first
` { "name": "order", "version": "2.0.0" }, `// ← Installed second
` { "name": "payment", "version": "1.5.0" } `// ← Installed third
` ]}Important: Order dependencies by placing prerequisite modules first!
Related Commands
- blueprint validate - Validate blueprint structure and business rules
- blueprint describe - Preview blueprint before installation
- blueprint config - Generate configs before installation
- blueprint list - Verify installation results
- module install - Install single module
