Blueprint Download Command
Essential knowledge
Intended Audience:
Technical User
Author:
Marco Heuer
Changed on:
30 Apr 2026
Overview
Learn how to use the`blueprint download` command to retrieve all module archives defined in a manifest without installing them. This guide enables implementing partners to archive modules for offline use, inspect contents, or build local repositories for air-gapped environments.For the business, this ensures disaster recovery readiness and simplifies distribution by creating a portable snapshot of a specific solution version. Note: This is a read-only operation and does not require Fluent Commerce authentication, though S3 sources still require local AWS credentials.Key points
- Purpose: Downloads blueprint module ZIPs to a local directory (
`-o`or`--output`) without applying any changes to an account. - Smart Downloads: Automatically skips files that already exist in the target folder, allowing you to easily resume interrupted downloads.
- Sources: Supports multiple protocols including HTTPS, S3 (requires AWS credentials), and local file system paths.
- Verification: Ideal for auditing module contents, performing version comparisons, or staging artifacts for CI/CD pipelines.
- Formatting: Automatically sanitizes namespaced modules (e.g.,
`acme/core`becomes`acme-core-v1.zip`) for consistent file naming.
The
├── acme-base-module-2.0.0.zip
├── acme-custom-order-module-2.5.2.zip
└── mycompany-payment-extension-1.8.0.zip
Output:
info: Output directory: /current/directory
info: Modules to download: 3
info: [1/3] Downloading: acme/base-module v2.0.0
info: → Downloaded: acme-base-module-2.0.0.zip
info: [2/3] Downloading: acme/custom-order-module v2.5.2
info: → Downloaded: acme-custom-order-module-2.5.2.zip
info: [3/3] Downloading: mycompany/payment-extension v1.8.0
info: → Downloaded: mycompany-payment-extension-1.8.0.zip
info: ═══════════════════════════════════════════════
info: Download Summary
info: ═══════════════════════════════════════════════
info: Blueprint: retail-order-management v1.0.0
info: Output directory: /current/directory
info:
info: Results:
┌────────────────────────────────────────────┬─────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────┐
│ Module │ Version │ Status │ File │
├────────────────────────────────────────────┼─────────┼─────────────┼──────────────────────────────────────────────────────┤
│ acme/base-module │ 2.0.0 │ + Success │ acme-base-module-2.0.0.zip │
│ acme/custom-order-module │ 2.5.2 │ + Success │ acme-custom-order-module-2.5.2.zip │
│ mycompany/payment-extension │ 1.8.0 │ + Success │ mycompany-payment-extension-1.8.0.zip │
└────────────────────────────────────────────┴─────────┴─────────────┴──────────────────────────────────────────────────────┘
info: + Downloaded: 3
info: [SUCCESS] All modules downloaded successfully
or
Result: All modules downloaded to
Output (second run):
info: → Already exists, skipping: acme-base-module-2.0.0.zip
info: [2/5] Downloading: acme/custom-order-module v2.5.2
info: → Already exists, skipping: acme-custom-order-module-2.5.2.zip
info: [3/5] Downloading: mycompany/payment-extension v1.8.0
info: → Downloaded: mycompany-payment-extension-1.8.0.zip
...
info: + Downloaded: 3
info: - Skipped: 2
Benefits: - No duplicate downloads - Safe to run multiple times - Automatically resumes from where it left off
fluent blueprint download staging-blueprint.json -o ./modules/staging
fluent blueprint download prod-blueprint.json -o ./modules/prod
unzip acme-base-module-2.0.0.zip -d core-module
ls -la core-module/assets/
sha256sum *.zip > checksums.txt
"modules": [
{
"name": "acme/base-module",
"version": "2.0.0"
}
]
}
Downloaded from:
"modules": [
{
"name": "custom-module",
"version": "1.0.0",
"modulePath": "https://example.com/modules/custom-module-1.0.0.zip"
}
]
}
"modules": [
{
"name": "internal-module",
"version": "1.5.0",
"modulePath": "s3://my-bucket/modules/internal-module-1.5.0.zip"
}
]
}
Note: Requires AWS credentials configured in environment
"modules": [
{
"name": "dev-module",
"version": "1.0.0",
"modulePath": "/local/path/dev-module-1.0.0.zip"
}
]
}
Copied to output directory
"modules": [
{
"name": "acme/base-module",
"version": "2.0.0",
"modulePath": "s3://my-bucket/modules/"
}
]
}
Constructs:
Solution: Verify blueprint file path exists
Possible causes: 1. Network connectivity issues 2. Invalid URL 3. Authentication required (S3) 4. File not found (404)Solutions: 1. Check network connection 2. Verify URL is correct and accessible 3. Ensure AWS credentials configured for S3 4. Confirm module exists at specified location
Solution: Blueprint should reference archive files (.zip), not directories
Solutions: 1. Use writable output directory 2. Check directory permissions 3. Use
jq '.modules = [.modules[2], .modules[3]]' blueprint.json > part2.json
fluent blueprint download part2.json -o ./modules &
wait
{
"name": "@mycompany/fluent-modules",
"version": "1.0.0",
"files": ["dist/modules/*.zip"]
}
EOF
`blueprint download` command downloads all module archive files (ZIPs) defined in a blueprint to a local directory without installing them.This is useful for: - Archiving modules for offline use - Preparing modules for distribution - Inspecting module contents before installation - Building a local module repositorySyntax
`fluent blueprint download <blueprint> [options]`Arguments
| Argument | Description | Required |
`<blueprint>` | Path to blueprint JSON file | Yes |
Options
| Option | Description | Required | Default |
`-o, --output <directory>` | Output directory for downloaded modules | No | Current directory (`.`) |
Authentication
This command does not require authentication as it only downloads publicly accessible modules or uses local file paths.How it Works
For each module in the blueprint:- Check if Already Downloaded - If file already exists in output directory: skip download - No overwrite of existing files - Allows resuming interrupted downloads
- Determine Source - Local file path: Copy to output directory - HTTP/HTTPS URL: Download from web - S3 URL (s3://): Download from S3 bucket - Reference module: Resolve URL and download from Fluent registry
- Download Module - Module archive is downloaded to output directory - Original filename is preserved - No extraction or modification of archives
- Track Results - Success, skipped, and failure counts tracked - Summary table displayed at end
Output
The command displays: - Progress for each module download - Source type (HTTP, S3, local, reference) - Downloaded filename - Final summary table with resultsStatus Indicators
| Icon | Status | Meaning |
`+` | Success | Module downloaded successfully |
`-` | Skipped | Module already exists in output directory |
`!` | Failed | Download failed or module not accessible |
Downloaded Files
Module archives are saved directly to the output directory with their original filenames:`output-directory/`├── acme-base-module-2.0.0.zip
├── acme-custom-order-module-2.5.2.zip
└── mycompany-payment-extension-1.8.0.zip
File Naming Pattern
- Fluent reference modules:
`fc-module-{name}-{version}.zip`(e.g.,`fc-module-core-2.2.1.zip`) - Namespaced modules:
`{org-name}-{module-name}-{version}.zip`(e.g.,`acme-custom-order-module-2.5.2.zip`, slashes replaced with hyphens) - Custom modules: Filename from URL or path
- S3 modules: Filename from S3 key
Usage Examples
Basic Usage
Download all modules to current directory:`fluent blueprint download accelerator.json`Output:
`info: Downloading modules from blueprint: retail-order-management v1.0.0`info: Output directory: /current/directory
info: Modules to download: 3
info: [1/3] Downloading: acme/base-module v2.0.0
info: → Downloaded: acme-base-module-2.0.0.zip
info: [2/3] Downloading: acme/custom-order-module v2.5.2
info: → Downloaded: acme-custom-order-module-2.5.2.zip
info: [3/3] Downloading: mycompany/payment-extension v1.8.0
info: → Downloaded: mycompany-payment-extension-1.8.0.zip
info: ═══════════════════════════════════════════════
info: Download Summary
info: ═══════════════════════════════════════════════
info: Blueprint: retail-order-management v1.0.0
info: Output directory: /current/directory
info:
info: Results:
┌────────────────────────────────────────────┬─────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────┐
│ Module │ Version │ Status │ File │
├────────────────────────────────────────────┼─────────┼─────────────┼──────────────────────────────────────────────────────┤
│ acme/base-module │ 2.0.0 │ + Success │ acme-base-module-2.0.0.zip │
│ acme/custom-order-module │ 2.5.2 │ + Success │ acme-custom-order-module-2.5.2.zip │
│ mycompany/payment-extension │ 1.8.0 │ + Success │ mycompany-payment-extension-1.8.0.zip │
└────────────────────────────────────────────┴─────────┴─────────────┴──────────────────────────────────────────────────────┘
info: + Downloaded: 3
info: [SUCCESS] All modules downloaded successfully
Specify Output Directory
Download to specific directory:`fluent blueprint download accelerator.json -o /path/to/modules`or
`fluent blueprint download accelerator.json --output /path/to/modules`Result: All modules downloaded to
`/path/to/modules/`Resume Interrupted Downloads
If a download is interrupted (network failure, Ctrl+C, etc.), simply re-run the same command:`# First attempt - interrupted after downloading 2 of 5 modules
`fluent blueprint download accelerator.json -o ./modules`# Network error occurs...
``# Re-run the same command - modules 1-2 automatically skipped
`fluent blueprint download accelerator.json -o ./modulesOutput (second run):
`info: [1/5] Downloading: acme/base-module v2.0.0`info: → Already exists, skipping: acme-base-module-2.0.0.zip
info: [2/5] Downloading: acme/custom-order-module v2.5.2
info: → Already exists, skipping: acme-custom-order-module-2.5.2.zip
info: [3/5] Downloading: mycompany/payment-extension v1.8.0
info: → Downloaded: mycompany-payment-extension-1.8.0.zip
...
info: + Downloaded: 3
info: - Skipped: 2
Benefits: - No duplicate downloads - Safe to run multiple times - Automatically resumes from where it left off
Download to Organised Directory
Create organised structure for different environments:`# Create environment-specific directories
`mkdir -p ./modules/dev ./modules/staging ./modules/prod`# Download same blueprint to each
`fluent blueprint download dev-blueprint.json -o ./modules/devfluent blueprint download staging-blueprint.json -o ./modules/staging
fluent blueprint download prod-blueprint.json -o ./modules/prod
Archive Modules
Download and archive for backup:`# Download modules
`fluent blueprint download accelerator.json -o ./module-archive`# Create timestamped archive
`tar czf modules-backup-`$(date +%Y%m%d).tar.gz ./module-archive/*.zip`Use Cases
1. Offline Module Repository
Create local repository for air-gapped environments:`# Download all modules
`fluent blueprint download blueprint.json -o /local/repository`# Transfer repository to offline environment
`rsync -av /local/repository/ offline-server:/modules/2. Module Inspection
Download and inspect module contents:`# Download modules
`fluent blueprint download blueprint.json -o ./modules-to-inspect`# Extract and inspect
`cd modules-to-inspectunzip acme-base-module-2.0.0.zip -d core-module
ls -la core-module/assets/
3. Version Comparison
Download different versions for comparison:`# Download v1.0.0
`fluent blueprint download blueprint-v1.json -o ./modules-v1`# Download v2.0.0
`fluent blueprint download blueprint-v2.json -o ./modules-v2`# Compare
`diff -r modules-v1/ modules-v2/4. CI/CD Pipeline
Integrate into build pipeline:`#!/bin/bash``# Download modules for deployment
`fluent blueprint download production.json -o ./artifacts/modules`# Verify checksums
`cd artifacts/modulessha256sum *.zip > checksums.txt
`# Upload to artifact repository
`aws s3 sync . s3://artifacts/modules/`$(git rev-parse HEAD)/`Modules Sources
Reference Modules
Modules from Fluent's official registry:`{`"modules": [
{
"name": "acme/base-module",
"version": "2.0.0"
}
]
}
Downloaded from:
`https://modules.fluentcommerce.com/acme/base-module/2.0.0`HTTP/HTTPS Modules
Custom modules hosted on web servers:`{`"modules": [
{
"name": "custom-module",
"version": "1.0.0",
"modulePath": "https://example.com/modules/custom-module-1.0.0.zip"
}
]
}
S3 Modules
Modules stored in S3 buckets:`{`"modules": [
{
"name": "internal-module",
"version": "1.5.0",
"modulePath": "s3://my-bucket/modules/internal-module-1.5.0.zip"
}
]
}
Note: Requires AWS credentials configured in environment
Local Modules
Local module archives:`{`"modules": [
{
"name": "dev-module",
"version": "1.0.0",
"modulePath": "/local/path/dev-module-1.0.0.zip"
}
]
}
Copied to output directory
Folder Paths
Modules in folders (filename auto-generated):`{`"modules": [
{
"name": "acme/base-module",
"version": "2.0.0",
"modulePath": "s3://my-bucket/modules/"
}
]
}
Constructs:
`s3://my-bucket/modules/acme-base-module-2.0.0.zip`Error Handling
Blueprint Not Found
Error:`error: Blueprint file not found: accelerator.json`Solution: Verify blueprint file path exists
Download Failed
Error:`error: → Failed to download module`Possible causes: 1. Network connectivity issues 2. Invalid URL 3. Authentication required (S3) 4. File not found (404)Solutions: 1. Check network connection 2. Verify URL is correct and accessible 3. Ensure AWS credentials configured for S3 4. Confirm module exists at specified location
Directory Path
Error:`error: → Module path is a directory, not an archive. Skipping.`Solution: Blueprint should reference archive files (.zip), not directories
Permission Denied
Error:`error: EACCES: permission denied, mkdir '/restricted/path'`Solutions: 1. Use writable output directory 2. Check directory permissions 3. Use
`sudo` if necessary (not recommended)Best Practices
Before Download
- Validate blueprint with
`validate`command - Verify blueprint with
`describe`command - Check disk space for all modules
- Ensure network connectivity for remote modules
- Configure AWS credentials for S3 modules
After Download
- Verify checksums if provided
- Scan for malware for external modules
- Test extraction before distribution
- Archive with metadata (date, blueprint version)
Organisation
- Use descriptive directories:
`./modules/blueprint-name/version/` - Include blueprint file: Copy blueprint.json to output directory
- Add README: Document download date and purpose
- Version control: Track blueprint definitions in git
Security
- Verify sources: Only download from trusted sources
- Use HTTPS: Prefer HTTPS over HTTP
- Check permissions: Verify file permissions after download
- Audit downloads: Log what was downloaded and when
Advanced Usage
Download Subset of Modules
Create custom blueprint with subset:`# Extract specific modules
`jq '.modules = [.modules[0], .modules[2]]' full-blueprint.json > subset.json`# Download subset
`fluent blueprint download subset.json -o ./subset-modulesParallel Downloads
While the command downloads sequentially, you can split blueprints:`# Split blueprint into chunks
`jq '.modules = [.modules[0], .modules[1]]' blueprint.json > part1.jsonjq '.modules = [.modules[2], .modules[3]]' blueprint.json > part2.json
`# Download in parallel
`fluent blueprint download part1.json -o ./modules &fluent blueprint download part2.json -o ./modules &
wait
Integration with Package Managers
Create npm package with downloaded modules:`# Download modules
`fluent blueprint download blueprint.json -o ./dist/modules`# Add to package.json
`cat > package.json <<EOF{
"name": "@mycompany/fluent-modules",
"version": "1.0.0",
"files": ["dist/modules/*.zip"]
}
EOF
`# Publish
`npm publishRelated Commands
- blueprint validate - Validate blueprint before downloading
- blueprint describe - Preview blueprint before downloading
- blueprint install - Download and install modules
- blueprint config - Generate config files for modules
