Fluent Commerce Logo
Docs
Help & Feedback

Fluent CLI Reference (v2.x.x)

Essential knowledge

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

20 Aug 2026

Overview

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.

Key points

  • Profile Management: Use `profile create` to securely store account IDs, client secrets, and base URLs. Profiles serve as the foundation for all subsequent commands.
  • Module Lifecycle: Supports the full lifecycle: `create` from templates, `config` for environment settings, and `install` for sequential asset deployment.
  • Asset Processing Order: Assets are processed in a specific dependency-aware order (e.g., `rules` and `locations` before `workflows`) to ensure system stability.
  • Workflow Operations: Features robust `download` and `list` commands with `--json` support, enabling advanced data manipulation using tools like `jq.
  • Environment Context: Most commands require a `-p` (profile) and `-r` (retailer) flag to define the target environment.
  • Batch Operations: The `blueprint` command allows for high-volume setup tasks, essential for large-scale data migrations or initial account provisioning.
  • Logging & Debugging: Use the `--debug` flag to resolve connectivity or validation issues by viewing the raw communication between the CLI and Fluent APIs.
The Fluent CLI is the official Command Line Interface for interacting with Fluent Commerce Accounts and Modules. It provides comprehensive functionality for managing profiles, retailers, modules, workflows, and various system assets.

Installation

`npm install -g https://downloads.fluentcommerce.com/v1.0.0/fluent-cli/release/latest`Requirements:
  • Node.js: >=22.20.0 <25.0.0
  • npm: >=10.5.0

Global Options

All commands support these global options:
OptionDescription
`-v, --version`Returns the installed version of the Fluent CLI
`-d, --debug`Enable verbose debug logging (conflicts with `--quiet`)
`-q, --quiet`Enable quiet logging (conflicts with `--debug`)
`-h, --help`Show help information

Command Structure

`fluent <command> <subcommand> <argument> [options]`

Commands Overview

Profile Management

`profile create`Creates a profile folder in `<user_home_dir>/.fluentcommerce/` to securely store Account and Authentication information.Usage: `fluent profile create <profile> [options]`Arguments: - `<profile>` - The Profile name (required)Options: - `--id <id>` - The Fluent Account Id (required) - `--username <username>` - The Fluent Account Admin Username (required) - `--password <password>` - The Fluent Account Admin Password (required) - `--client-secret <clientSecret>` - The Fluent Account Client Secret (required) - `--base-url <baseUrl>` - The Fluent Account base API URL. Usually 'https://<account_id>...fluentcommerce.com/' (required)Example:
`fluent profile create dev_account \`
 --id ACCOUNT123 \
 --username admin@example.com \
 --password secretpass \
 --client-secret client123 \
 --base-url https://account123.api.fluentcommerce.com

`profile update`

Updates the profile, retailer, or user profile files in `<user_home_dir>/.fluentcommerce/<profile>`.Usage: `fluent profile update <profile> [options]`Arguments: - `<profile>` - The Profile name (required)Options: - `--user <user>` - The User reference to update the Profile or Retailer default User - `--username <username>` - The User username (required if --password provided) - `--password <password>` - The User password (required if --username provided) - `--retailer <retailer>` - The Retailer reference to add or update (required if --id, --username, and/or --password provided) - `--id <id>` - The Retailer Id (required when adding a Retailer profile)Examples:
`# Update the default Account User Ref in profile.json
`fluent profile update dev_acme --user my_super_user

`# Update the default Retailer User Ref
`fluent profile update dev_acme --retailer fc_fashion --user my_retailer_user

`# Add a new Retailer and User
`fluent profile update dev_acme --retailer fc_fashion --id 1 --username fc_fashion_admin --password S3CR37

`# Add a new User
`fluent profile update dev_acme --username fc_fashion_super --password S3CR37

`profile export`

Export a profile to a specified format (currently only Postman is supported).Usage: `fluent profile export <profile> [options]`Arguments: - `<profile>` - The Profile name (required)Options: - `--format <format>` - The target Export format. Currently only `postman` is supported (required) - `--retailer <retailer>` - A Retailer Ref to include in the export (repeatable)Example:
`fluent profile export dev_acme --format postman --retailer retailer1 --retailer retailer2`

Retailer Management

`retailer create`

Creates a new Retailer on the Account for the given Profile.Usage: `fluent retailer create <retailer> [options]`Arguments: - `<retailer>` - The Retailer Ref to create (required)Options: - `-p, --profile <profile>` - The Profile name to use (required) - `--trading-name <tradingName>` - The Trading Name of the Retailer (defaults to `<retailer>`) - `--region <region>` - The region of the Retailer - `--phone-number <phoneNumber>` - The phone number of the Retailer - `--email <email>` - The email of the Retailer (required) - `--website <website>` - The website of the RetailerExample:
`fluent retailer create my_retailer \`
 -p dev_profile \
 --trading-name "My Retail Store" \
 --email admin@mystore.com \
 --website https://mystore.com

Module Management

`module create`

Generates a new module structure from a standardized template.Usage: `fluent module create [template_path] [options]`Arguments: - `[template_path]` - The location of the template archive. Can be a zip file or URL. Default uses the latest template from the Fluent repositoryOptions: - `-b, --base-dir <directory>` - The directory to unzip the template into (default: current directory) - `-n, --name <module-name>` - The name of the module to set in the module's package fileExample:
`fluent module create --base-dir ./my-module --name my-custom-module`

`module list`

Lists all modules in an account.Usage: `fluent module list [options]`Options: - `-p, --profile <profile>` - The Profile to use (required)Example:
`fluent module list -p dev_profile`

`module install`

Installs a Module on an Account.Usage: `fluent module install <module> [options]`Arguments: - `<module>` - The path to the Module. Can be a directory, zip file or URL (required)Options: - `-p, --profile <profile>` - The Profile to use (required) - `-r, --retailer <retailer>` - The Retailer to use (required) - `-c, --config <config>` - The config file to use - `-w, --wait <millisecs>` - The time period to wait between tasks (default: 2000) - `--base-dir <directory>` - The base directory to extract the module archive into (default: .tmp) - `--module-version <moduleversion>` - The module version to use. Only needed for Fluent reference modules (default: latest) - `-i, --include <assets...>` - Asset(s) to include. Only these will be installed - `-e, --exclude <assets...>` - Asset(s) to ignore - `-f, --force` - Force the module installation, even if the same or greater module version is already installedExample:
`fluent module install ./my-module \`
 -p dev_profile \
 -r my_retailer \
 --config ./config.json \
 --include settings users

`module config`

Generates a new Module Config file based on the module's template.Usage: `fluent module config <module> [options]`Arguments: - `<module>` - The path to the Module. Can be a directory, zip file or URL (required)Options: - `-p, --profile <profile>` - The Profile to use (required) - `-r, --retailer <retailer>` - The Retailer to use (required) - `--base-dir <directory>` - The base directory to extract the module archive into (default: .tmp) - `--module-version <moduleversion>` - The module version to use (default: latest)Example: `fluent module config ./my-module -p dev_profile -r my_retailer`

`module describe`

Describes a module's details and structure.Usage: `fluent module describe <module> [options]`

Workflow Management

`workflow list`

List workflow details for all workflows for a given retailer.Usage: `fluent workflow list [options]`Options: - `-p, --profile <profile>` - The profile to use (required) - `-r, --retailer <retailer>` - The retailer to use (required) - `--json` - Output as JSON format for processing with tools like jqExamples:Standard table output:
`fluent workflow list -p dev_profile -r my_retailer`
JSON output for processing with jq:
`fluent workflow list -p dev_profile -r my_retailer --json`
JSON Output Format:
`[`
 {
   "type": "ORDER",
   "subtype": "CC",
   "name": "ORDER::CC",
   "version": "1.0",
   "createdOn": "2024-01-15T10:30:00Z"
 },
 {
   "type": "FULFILMENT",
   "subtype": "HD",
   "name": "FULFILMENT::HD",
   "version": "2.1",
   "createdOn": "2024-02-20T14:45:00Z"
 }
]Processing with jq:
`# Get only workflow names
`fluent workflow list -p dev_profile -r my_retailer --json | jq -r '.[].name'

`# Filter by entity type
`fluent workflow list -p dev_profile -r my_retailer --json | jq '.[] | select(.type == "ORDER")'

`# Count workflows by type
`fluent workflow list -p dev_profile -r my_retailer --json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

`workflow download`

Download one or all workflows from a retailer.Usage: `fluent workflow download [options]
`Options: - `-p, --profile <profile>` - The profile to use (required) - `-r, --retailer <name>` - The retailer ref (required) - `-o, --output-folder <output>` - The destination folder for the workflows (default: current directory) - `-w, --workflow <name>` - The workflow name to download. If not provided, all workflows will be downloaded (default: all) - `--json` - Output as JSON format for processing with tools like jq. When enabled, workflows are written to stdout instead of files.Examples:Download to files (default):
`# Download all workflows to files
`fluent workflow download -p dev_profile -r my_retailer -o ./workflows

`# Download specific workflow to file
`fluent workflow download -p dev_profile -r my_retailer -w ORDER::CC -o ./workflows
JSON output for processing:
`# Output all workflows as JSON
`fluent workflow download -p dev_profile -r my_retailer --json

`# Output specific workflow as JSON
`fluent workflow download -p dev_profile -r my_retailer -w ORDER::CC --json
JSON Output Format:When downloading a single workflow:
`{`
 "name": "ORDER::CC",
 "entityType": "ORDER",
 "entitySubtype": "CC",
 "version": "1.0",
 "description": "Order workflow for Credit Card orders",
 "settings": {},
 "rulesets": [
   {
     "name": "CREATE",
     "description": "Create order ruleset",
     "type": "ORDER",
     "eventType": "NORMAL",
     "rules": [
       {
         "name": "ACME.core.SetState",
         "props": [
           {
             "status": "BOOKED"
           }
         ]
       }
     ],
     "triggers": [
       {
         "status": "PICK_PACK"
       }
     ],
     "userActions": []
   }
 ],
 "statuses": [
   {
     "category": "BOOKING",
     "entityType": "ORDER",
     "status": "BOOKED"
   }
 ]
}When downloading all workflows:
`[`
 {
   "name": "ORDER::CC",
   "workflow": {
     "name": "ORDER::CC",
     "entityType": "ORDER",
     "entitySubtype": "CC",
     "version": "1.0",
     "..."
   }
 },
 {
   "name": "FULFILMENT::HD",
   "workflow": {
     "name": "FULFILMENT::HD",
     "entityType": "FULFILMENT",
     "entitySubtype": "HD",
     "version": "2.1",
     "..."
   }
 }
]
Processing with jq:
`# Extract workflow names from all workflows
`fluent workflow download -p dev_profile -r my_retailer --json | jq -r '.[].name'

`# Get all rulesets from a specific workflow
`fluent workflow download -p dev_profile -r my_retailer -w ORDER::CC --json | jq '.rulesets'

`# Extract all status definitions from all workflows
`fluent workflow download -p dev_profile -r my_retailer --json | jq '[.[].workflow.statuses] | flatten | unique_by(.status)'

`# Save workflows with specific entity type to files
`fluent workflow download -p dev_profile -r my_retailer --json | jq '.[] | select(.workflow.entityType == "ORDER")' | split -l 1 - workflow-

`# Validate workflow structure (check for required fields)
`fluent workflow download -p dev_profile -r my_retailer -w ORDER::CC --json | jq 'has("name") and has("rulesets") and has("statuses")'

`workflow merge`

Merge workflow files and manage workflow logs.Usage: `fluent workflow merge [options]
`

Workflow Log Management

`workflowlog list`

List workflow logs for a given retailer.Usage: `fluent workflowlog list [options]
`Options: - `-p, --profile <profile>` - The profile to use (required) - `-r, --retailer <name>` - The retailer ref (required)Example:
`fluent workflowlog list -p dev_profile -r my_retailer`

`workflowlog describe`

Describe details of a specific workflow log.Usage: `fluent workflowlog describe [options]`

`workflowlog insert`

Insert a new workflow log entry.Usage: `fluent workflowlog insert [options]
`

`workflowlog delete`

Delete a workflow log entry.Usage: `fluent workflowlog delete [options]
`

Extract Operations

These commands extract data from the Fluent platform for analysis or backup purposes.

`extract catalogues`

Extract all catalogues and their metadata.Usage: `fluent extract catalogues [options]
`Options: - `-p, --profile <profile>` - The profile to use - `-r, --retailer <retailer>` - The retailer to use

`extract inventory`

Extract inventory data.Usage: `fluent extract inventory [options]
`

`extract role-permissions`

Extract role permissions data.Usage: `fluent extract role-permissions [options]
`

`extract user-permissions`

Extract user permissions data.Usage: `fluent extract user-permissions [options]
`

Configuration 

Profile Structure

Profiles are stored in `~/.fluentcommerce/<profile-name>/` with the following structure:
`~/.fluentcommerce/`
├── <profile-name>/
│   ├── profile.json              # Account configuration
│   ├── user.<username>.json      # User credentials
│   └── retailer.<retailer>.json  # Retailer configuration

Environment Variables

The CLI respects standard Node.js environment variables and can be configured through profile files.

Module Structure

Modules follow this standardized structure:
`module/`
├── assets/                       # Module assets
│   ├── workflows/               # Workflow definitions
│   ├── workflow-fragments/      # Workflow fragments
│   ├── users/                   # User definitions
│   ├── roles/                   # Role definitions
│   ├── settings/                # Settings
│   ├── locations/               # Location definitions
│   ├── networks/                # Network definitions
│   ├── carriers/                # Carrier definitions
│   ├── product-catalogues/      # Product catalogue definitions
│   ├── inventory-catalogues/    # Inventory catalogue definitions
│   ├── virtual-catalogues/      # Virtual catalogue definitions
│   ├── categories/              # Category definitions
│   ├── products/                # Product definitions
│   ├── inventory/               # Inventory definitions
│   ├── control-groups/          # Control group definitions
│   ├── controls/                # Control definitions
│   └── rules/                   # Business rules
├── resources/
│   ├── module.json              # Module metadata
│   └── module.config.json       # Module configuration template
└── extensionTasks/              # Custom extension tasks (optional)

`
`Default Values and Constants

Asset Processing Order

When installing modules, assets are processed in this default order:
  • rules
  • locations
  • settings
  • workflows
  • workflow-fragments
  • roles
  • users
  • networks
  • carriers
  • product-catalogues
  • categories
  • products
  • inventory-catalogues
  • control-groups
  • controls
  • virtual-catalogues
  • inventory

Error Handling

The CLI uses structured error handling with these result types: 
  • `SUCCESS` - Operation completed successfully 
  • `WARNING` - Operation completed with warnings 
  • `ERROR` - Operation failed
Exit codes: 
  • `0` - Success 
  • `1` - Error

Logging

The CLI supports three logging levels: 
  • `info` (default) - Standard information 
  • `debug` - Verbose debugging information 
  • `warn` - Warnings and errors only
Use `--debug` for verbose output or `--quiet` for minimal output.

Help and Support

  • Get command help: `fluent <command> -h`
  • Get subcommand help: `fluent <command> <subcommand> -h`
  • Full documentation: Fluent CLI Docs
  • Support: Service Desk

Related content

CLI Blueprint Troubleshooting Guide
Edited 117 days ago
Fluent CLI Blueprints Guide
Edited 5 days ago
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.
Fluent CLI Reference
Edited 5 days ago
The Fluent CLI provides command line tooling for interacting with Fluent Accounts and Modules.UsageThe Fluent CLI is activated by typing the keyword `fluent` into a terminal command line, followed by a Command, Subcommand, Argument, and Options:`fluent <command> <subcommand> <argument> [options]`
  • The `<command>` will refer to a noun (or “a thing”).
  • The `<subcommand>` will refer to a verb (or action).
  • The `<argument>` is the primary required name of the “thing” identified by the `<command>`.
  • The `[options]` may include required or optional additional parameters to be used by the `<command>` and `<subcommand>`.
What is a Blueprint?
Edited 5 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.
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