Blueprint Describe Command
Essential knowledge
Intended Audience:
Technical User
Author:
Marco Heuer
Changed on:
20 Aug 2026
Overview
Learn to use the`blueprint describe` command to preview the contents of a JSON manifest file before deployment. This article enables implementing partners to inspect module versions, source locations, and conflict rules locally without needing authentication.For the business, this provides a critical safety check, ensuring that intended configurations (such as specific order management workflows) are verified before any changes reach the account. Note: This is a read-only operation; it identifies potential issues but does not replace the `blueprint validate` command for structural health checks.Key points
- Purpose: Use
`fluent blueprint describe <blueprint>`to preview the details of a JSON manifest file locally. - No Auth Required: This is a read-only local operation; no credentials or active internet connection are needed.
- Metadata: Displays blueprint name, version, authors, and searchable tags.
- Module Inventory: Lists every module to be installed, including its exact version, source (registry vs. custom path), and asset filters (includes/excludes).
- Conflict Rules: Shows a table of incompatible modules/blueprints to prevent breaking existing setups.
- Best Practice: Use this for a pre-installation review or to compare version differences before deploying.
The
Output:
Name: retail-order-management
Version: 1.0.0
Description: Complete order management solution for retail
Created: 2024-12-01T00:00:00Z
Authors:
- ACME Corp <support@acme.com> (https://acme.com)
Modules (5)
┌──────────────────────────────────────────┬─────────┬──────────┬─────────────────┐
│ name │ version │ source │ filters │
├──────────────────────────────────────────┼─────────┼──────────┼─────────────────┤
│ acme/base-module │ 2.0.0 │ registry │ none │
│ acme/custom-order-module │ 2.5.2 │ registry │ excludes: 2 │
│ mycompany/payment-extension │ 1.8.0 │ registry │ none │
│ mycompany/shipping-extension │ 1.5.0 │ registry │ includes: 3 │
│ custom-integration-module │ 1.0.0 │ ./mods/ │ none │
└──────────────────────────────────────────┴─────────┴──────────┴─────────────────┘
Conflicts (1)
┌──────────────────────┬────────┬─────────┬──────────────────────────────┐
│ name │ type │ version │ reason │
├──────────────────────┼────────┼─────────┼──────────────────────────────┤
│ legacy-order-module │ module │ * │ Replaced by custom-order-module│
└──────────────────────┴────────┴─────────┴──────────────────────────────┘
Tags: retail, order-management, omni-channel
fluent blueprint describe accelerator-v2.json > v2.txt
diff v1.txt v2.txt
Action:
Solutions:
Solutions:
Solutions:
Solution: Convert YAML to JSON or ensure file has
`blueprint describe` command displays detailed information about a blueprint JSON file without requiring authentication or making any changes. Use this to preview blueprint contents before installation.Syntax
`fluent blueprint describe <blueprint>`Arguments
| Argument | Description | Required |
`<blueprint>` | Path to blueprint JSON file | Yes |
Options
This command has no options and does not require authentication.Authentication
Not required - This is a read-only local operation that inspects the blueprint file.Output Sections
1. Blueprint Metadata
Core information about the blueprint:- Name
- Version
- Description
- Created date
- Updated date (if applicable)
- Author(s)
- Type
2. Modules Table
List of all modules to be installed:- name - Full module name
- version - Version constraint
- source - Module source (registry or custom path)
- filters - Include/exclude rules
3. Conflicts (if defined)
Incompatible modules or blueprints:- name - Conflicting item name
- type - "module" or "blueprint"
- version - Version constraint
- reason - Why it conflicts
4. Tags (if defined)
Searchable labels for blueprint categorisationUsage Examples
Basic Usage
Describe a blueprint file:`fluent blueprint describe accelerator.json`Output:
`Blueprint Details`Name: retail-order-management
Version: 1.0.0
Description: Complete order management solution for retail
Created: 2024-12-01T00:00:00Z
Authors:
- ACME Corp <support@acme.com> (https://acme.com)
Modules (5)
┌──────────────────────────────────────────┬─────────┬──────────┬─────────────────┐
│ name │ version │ source │ filters │
├──────────────────────────────────────────┼─────────┼──────────┼─────────────────┤
│ acme/base-module │ 2.0.0 │ registry │ none │
│ acme/custom-order-module │ 2.5.2 │ registry │ excludes: 2 │
│ mycompany/payment-extension │ 1.8.0 │ registry │ none │
│ mycompany/shipping-extension │ 1.5.0 │ registry │ includes: 3 │
│ custom-integration-module │ 1.0.0 │ ./mods/ │ none │
└──────────────────────────────────────────┴─────────┴──────────┴─────────────────┘
Conflicts (1)
┌──────────────────────┬────────┬─────────┬──────────────────────────────┐
│ name │ type │ version │ reason │
├──────────────────────┼────────┼─────────┼──────────────────────────────┤
│ legacy-order-module │ module │ * │ Replaced by custom-order-module│
└──────────────────────┴────────┴─────────┴──────────────────────────────┘
Tags: retail, order-management, omni-channel
Relative Path
`fluent blueprint describe ./blueprints/my-accelerator.json`Absolute Path
`fluent blueprint describe /Users/john/accelerators/retail-v1.json`Remote URL (if supported)
`fluent blueprint describe https://example.com/blueprints/accelerator.json`Use Cases
Pre-Installation Review
Inspect blueprint before committing to installation:`# Review what will be installed
`fluent blueprint describe new-accelerator.json`# Check for conflicts with current setup
`fluent blueprint listBlueprint Preview and Validation
Preview blueprint content before validation and installation:`# Preview blueprint contents
`fluent blueprint describe accelerator.json`# Validate blueprint structure and business rules
`fluent blueprint validate accelerator.json`# Check module versions and sources in the preview
# Review conflict definitions
`Documentation Generation
Extract blueprint information for documentation:`fluent blueprint describe accelerator.json > blueprint-details.txt`Comparison
Compare different blueprint versions:`fluent blueprint describe accelerator-v1.json > v1.txt`fluent blueprint describe accelerator-v2.json > v2.txt
diff v1.txt v2.txt
Module Inventory
List modules without installation:`# Extract module list for planning
`fluent blueprint describe accelerator.json | grep "fluent-commerce"Understanding Output
Module Sources
Registry - Module will be downloaded from Fluent module repository - Uses module name and version for lookupCustom Path Module will be loaded from specified location and can be:- Relative path:
`./modules/my-module.zip` - Absolute path:
`/opt/modules/my-module.zip` - Directory:
`./modules/`(filename constructed from name+version) - URL:
`https://example.com/modules/my-module.zip`
Filter Types
- none - All module assets will be installed - No filtering applied
- includes: N - Only N specific assets will be installed - Examples: specific settings files, workflows
- excludes: N - N specific assets will be skipped - Examples: test data, documentation
Module Versions
Module versions must be exact:`2.5.0`- Exact version (valid)`latest`- Latest available version (valid)`^2.5.0`,`~2.5.0`,`>=2.5.0`- Ranges (invalid)
Conflict Matching
Conflict version constraints (ranges allowed):`*`- Matches any version`1.0.0`- Exact version match`^1.0.0`- Compatible versions (1.x.x)`~1.0.0`- Patch versions (1.0.x)`>=1.0.0`- Greater than or equal`<2.0.0`- Less than
Common Scenarios
Scenario 1: New Blueprint Review
Situation: Received a blueprint file, need to understand contents`fluent blueprint describe customer-blueprint.json`Action:
- Review module list - ensure familiar modules
- Check versions - verify compatibility
- Read conflict rules - understand restrictions
- Examine filters - know what gets installed
Scenario 2: Conflict Detection
Situation: Want to know if blueprint conflicts with current setup`# Step 1: Describe blueprint to see conflicts
`fluent blueprint describe new-blueprint.json`# Step 2: Check what's currently installed
`fluent blueprint list`# Step 3: Compare conflict rules with installed modules
`Scenario 3: Module Version Planning
Situation: Planning module versions for blueprint`# Review current blueprint
`fluent blueprint describe current-v1.json`# Check proposed changes
`fluent blueprint describe updated-v2.json`# Compare module versions between versions
`Error Handling
File Not Found
Error:`error: Blueprint file not found: accelerator.json`Solutions:
- Check file path spelling
- Use absolute path
- Verify file exists:
`ls -la accelerator.json`
Invalid JSON
Error:`error: Failed to parse blueprint: Unexpected token`Solutions:
- Validate JSON syntax:
`cat accelerator.json | jq .` - Check for trailing commas
- Verify quotes and brackets
Missing Required Fields
Error:`error: Blueprint must be a JSON object`Solutions:
- Ensure file contains a JSON object (not array)
- Verify required fields: name, version, modules
- Check blueprint structure against examples
Unsupported Format
Error:`error: Unsupported blueprint file format: .yaml. Only .json format is supported.`Solution: Convert YAML to JSON or ensure file has
`.json` extensionBlueprint File Checks
The describe command performs basic checks:- File exists and is readable
- Valid JSON syntax
- Blueprint is an object (not array)
`fluent blueprint validate accelerator.json`Related Commands
- Blueprint validate - Validate blueprint structure and business rules
- Blueprint install - Install blueprint modules
- Blueprint config - Generate module configs
- Blueprint list - View installed blueprints
