Fluent Commerce Logo
Docs
Help & Feedback

Fluent CLI Blueprints Guide

Essential knowledge

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

20 Aug 2026

Overview

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.

Key points

  • Definition: Blueprints are JSON manifest files used as "recipes" to deploy pre-configured module collections via the Fluent CLI.
  • Outcome: Enables rapid, consistent environment setup and automated version control for implementing partners.
  • Smart Installation: Automatically detects upgrades and skips unchanged modules; "Smart Resume" continues failed installs from the point of interruption.
  • Control: Use `--include` or `--exclude` for selective deployment and `blueprint config` to manage environment-specific settings.
  • Safety: Blocks incompatible modules and prevents accidental downgrades unless `--force` is applied.
  • Workflow: Design → Validate → Config → Install → Manage.

Quick Start

1# Option 1: Using an existing blueprint
2# 1. Preview blueprint contents
3fluent blueprint describe accelerator.json
4
5# 2. Generate module configurations
6fluent blueprint config accelerator.json -p myprofile -r RETAILER01
7
8# 3. Install accelerator
9fluent blueprint install accelerator.json -p myprofile -r RETAILER01
10
11# 4. Verify installation
12fluent blueprint list -p myprofile
13
14# Option 2: Creating a new blueprint from template
15# 1. Create template with reference modules
16fluent blueprint create --name "my-blueprint"
17
18# 2. Customise the generated file
19vi my-blueprint-1.0.0.json
20
21# 3. Validate your blueprint
22fluent blueprint validate my-blueprint-1.0.0.json
23
24# 4. Install your custom blueprint
25fluent blueprint install my-blueprint-1.0.0.json -p myprofile -r RETAILER01

Language: markdown

Name: Quick Start

Description:

Quick start commands to begin using Blueprints immeadiately.

Getting Started

  • Oveview - Understanding blueprints, structure, lifecycle, and module types
  • Reference modules (`core`, `order`, `inventory`, `fulfilment`)
  • Name-spaced modules (`acme/`, `mycompany/...`)

Commands

  • create - Create a blueprint template file with reference modules
  • validate - Validate a blueprint file against business rules and structural requirements
  • list - View installed blueprints in an account
  • describe - Preview blueprint file contents
  • download - Download all module archives from a blueprint to local directory
  • config - Generate module configuration files
  • install - Install blueprint modules with smart version comparison and selective installation

Help

Smart Version Comparison

Automatically detects upgrades, same versions, and downgrades using semantic versioning: - ⬆ Upgrades: Automatically installs newer versions without `--force` - ⊝ Same Version: Skips reinstallation (use `--force` to reinstall) - ⬇ Downgrades: Requires explicit `--force` flag for safety
`# Blueprint v1.1 has 2 upgraded modules, 3 unchanged
`fluent blueprint install retail-v1.1.json -p myprofile -r RETAILER01
`# ✓ Only the 2 upgraded modules are installed. Other modules are skipped.
`

Selective Installation

Install only specific modules or exclude modules from installation:
`# Install only core and order modules
`fluent blueprint install accelerator.json --include "core,order" -p myprofile -r RETAILER01

`# Install all except test modules
`fluent blueprint install accelerator.json --exclude "test-module" -p myprofile -r RETAILER01

Smart Resume

Installation automatically resumes from where it left off if interrupted. Already-installed modules are skipped without requiring manual tracking.
`# Installation fails on module 5 of 10
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

`# Just re-run - modules 1-4 automatically skipped
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

Conflict Prevention

Blueprints define incompatible modules and blueprints to prevent breaking installations.
`{`
 "conflicts": [
   {
     "name": "legacy-module",
     "type": "module",
     "version": "*",
     "reason": "Replaced by new-module"
   }
 ]
}

Selective Installation

Control which module assets are installed using include/exclude filters.
`{`
 "modules": [
   {
     "name": "acme/custom-order-module",
     "version": "2.5.2",
     "excludes": ["workflows", "rules"]
   }
 ]
}

Configuration Management

Generate, customise, and version-control module configurations before installation.
`fluent blueprint config accelerator.json -p prod -r PROD01`
`# Edit generated configs for production settings
`fluent blueprint install accelerator.json -p prod -r PROD01

New Environment Setup

`# Describe blueprint
`fluent blueprint describe retail-accelerator.json

`# Validate blueprint
`fluent blueprint validate retail-accelerator.json

`# Generate configs
`fluent blueprint config retail-accelerator.json -p myprofile -r RETAILER01

`# Review configs
`ls -la module.config.*.json

`# Install
`fluent blueprint install retail-accelerator.json -p myprofile -r RETAILER01

`# Verify
`fluent blueprint list -p myprofile

Resume Failed Installation

`# Installation interrupted at module 7
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`# Network error...
`
`# Fix issue and resume (modules 1-6 skipped automatically)
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

Multi-Environment Deployment

`# Development
`fluent blueprint install accelerator.json -p dev -r DEV01

`# Staging
`fluent blueprint install accelerator.json -p staging -r STAGE01

`# Production (validate first)
`fluent blueprint install accelerator.json -p prod -r PROD01 --dry-run
fluent blueprint install accelerator.json -p prod -r PROD01

Blueprint Upgrade

`# Check current version
`fluent blueprint list -p myprofile

`# Preview new version
`fluent blueprint describe accelerator-v2.json

`# Install upgrade (only changed modules are reinstalled automatically!)
`fluent blueprint install accelerator-v2.json -p myprofile -r RETAILER01

`# Or install only a specific updated module
`fluent blueprint install accelerator-v2.json -p myprofile -r RETAILER01 --include "order"

`# Force reinstall ALL modules (rarely needed)
`fluent blueprint install accelerator-v2.json -p myprofile -r RETAILER01 --force
CommandPurposeAuthentication
`blueprint create --name <name>`Create template fileNone
`blueprint validate <file>`Validate blueprint fileNone
`blueprint list`Show installed blueprintsAccount
`blueprint describe <file>`Preview blueprintNone
`blueprint download <file>`Download modules locallyNone
`blueprint config <file>`Generate configsRetailer
`blueprint install <file>`Install modulesRetailer

Without --force (Default)

  • Checks each module individually with smart version comparison
  • Upgrades automatically when blueprint has newer version
  • Skips modules with same version (already installed)
  • Skips downgrades (shows warning, requires --force)
  • Installs only missing or upgraded modules

With --force

  • Reinstalls all modules regardless of version
  • Allows downgrades to older versions
  • Overwrites existing installations

Selective Installation (New)

  • `--include "module1,module2"`: Install only specified modules
  • `--exclude "module1,module2"`: Install all except specified modules
  • Cannot use both include and exclude together
  • Follows same pattern as `module install` command
CodeMeaning
0Success - all modules installed or appropriately skipped
1Blueprint file not found or invalid
2Conflicts detected - installation blocked
3Module installation failed - installation stopped

Blueprint Design

  • Use specific versions in production blueprints
  • Document conflicts with clear reasons
  • Test in non-production first
  • Version blueprints semantically
  • Include comprehensive metadata

Installation Strategy

  • Preview with `describe` before installing
  • Generate configs first for review
  • Use `--dry-run` to validate
  • Keep installation logs
  • Test in lower environments first

Configuration Management

  • Version control config files
  • Customise per environment
  • Document customisations
  • Backup before regenerating
  • Validate JSON syntax

Installation stops mid-way?

  • Just re-run the same command. Already-installed modules are automatically skipped.

Modules being skipped unexpectedly?

  • They're already installed. Use `blueprint list` to verify. Use `--force` to reinstall if needed.

Conflicts detected?

  • Remove conflicting modules first, or adjust the blueprint's conflict definitions.

Config files not found?

  • Generate them first with `blueprint config`, ensuring correct retailer reference.

Need more help?

See each command's documentation page for detailed examples: - Create Examples - Validate Examples - List Examples - Describe Examples - Config Examples - Install ExamplesFor issues, questions, or contributions, please refer to the main CLI documentation or contact your Fluent Commerce support team.

Related content

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.
CLI Blueprint Troubleshooting Guide
Edited 138 days ago
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.
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