Fluent Commerce Logo
Docs
Sign In

Fluent CLI Reference

Topic

Authors:

Lesley Dean, Marco Heuer

Changed on:

27 Feb 2025

Overview

The Fluent CLI provides command line tooling for interacting with Fluent Accounts and Modules.

Usage

The 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>`
    .

Top-level Options

Author:

Marco Heuer

Changed on:

27 Feb 2025

Overview

Global options to control the functioning of the CLI.

Key points

  • Show the CLI version and help screens
  • Increase and reduce log verbosity

As one would expect, the tool has several top-level options:

  • `--version`
    to show the version of the CLI, send this along with any bug reports.
  • `--help`
    to show help. Depending on the level, it will list the commands and also subcommands and their arguments and recognized options.

To control the verbosity of the output:

  • `--debug`
    to increase the level of detail printed to stdout.
  • `--quiet`
    to reduce the logging level and only show warnings and errors.

Profile Command

Author:

Lesley Dean

Changed on:

27 Feb 2025

Overview

The

`profile`
command directs the CLI to perform an action on a Profile. A Profile is simply a folder which stores information about the specific Fluent Account you are interacting with via the CLI.

Key points

  • Subcommands:
    • `create`
    • `update`
    • `export`

`create`

The

`create`
command will create a new Profile in the
`.fluentcommerce`
folder in your user’s home directory. It will create a folder with the provided Profile name, and
`profile.json`
file to store the Account specific details, and a
`user.<account_admin>.json`
file to store the Account user’s secrets (credentials).

Usage

1fluent profile create <profile_name> [options]

Language: sh

Name: Profile Create

Description:

Example usage of the Fluent CLI Profile Create command

Arguments

Argument Name

Description

Example

`profile_name`

The name of the profile to create

`my-acme-profile`

Options

Option Name

Description

Required

Default

Example

`--id`

A valid Fluent Account ID

 

N/A

`ACME`

`--base-url`

The Account specific API Url

 

N/A

`https://acme.sandbox.api.fluentretail.com`

`--username`

The Account Admin Username

 

N/A

`acme_admin`

`--password`

The Account Admin Password

 

N/A

`S3CR37`

`--client-secret`

The Account Client Secret

 

N/A

`abc123-xyz987-s3cr37`

Example

Let’s assume you have a Sandbox Account called

`ACME`
, with an Account Admin User called
`acme_admin`
and you create a Profile called
`my-acme-profile`
.

Command Example
1fluent profile create my-acme-profile --id ACME --base-url https://acme.sandbox.api.fluentretail.com --username acme_admin --password S3CR37 --client-secret abc123-xyz987-s3cr37

Language: sh

Name: Example Usage

Description:

Example of creating a new Profile

Profile Directory
1/Users/jonsnow/.fluentcommerce/my-acme-profile/
2  profile.json
3  user.acme_admin.json

Language: plain_text

Name: Profile Directory

Description:

Example of the Profile directory created as a result of the example command

`profile.json`
File
1{
2  "id": "ACME",
3  "baseUrl": "https://acme.sandbox.api.fluentretail.com",
4  "clientSecret": "abc123-xyz987-s3cr37",
5  "user": "acme_admin"
6}

Language: plain_text

Name: profile.json file

Description:

Example contents of the profile.json file

`user.acme_admin.json`
File
1{
2  "username": "acme_admin",
3  "password": "S3CR37"
4}

Language: plain_text

Name: user json file

Description:

Example contents of a user json file

`update`

The

`update`
command will update an existing Profile in the
`.fluentcommerce`
folder in your user’s home directory.

It can be used to perform the following actions:

  • Add a
    `retailer`
    to the profile
  • Add a
    `user`
    to the profile
  • Update the
    `user`
    reference on the profile
  • Update the
    `user`
    reference on a retailer

Usage

1fluent profile update <profile_name> [options]

Language: plain_text

Name: Profile Update Usage

Description:

Profile Update Command Usage

Arguments

Argument Name

Description

Example

`profile_name`

The name of the profile to create

`my-acme-profile`

Options

Option Name

Description

Required

Default

Example

`--user`

A User Reference (username)

*when updating a profile or retailer user reference

N/A

acme_admin

`--username`

The User’s Username

*when adding a user

N/A

acme_admin

`--password`

The User’s Password

*when adding a user

N/A

S3CR37

`--retailer`

A Retailer Reference

*when adding a retailer

N/A

fc_fashion

`--id`

A Retailer ID

*when adding a retailer

N/A

ACME

Example

Let’s assume you have the ACME Account Profile with a single Retailer

`fc_fashion`
, and want to add and update users and retailers to your ACME profile.

Command Examples:
1# Add a new User:
2fluent profile update my-acme-profile --username acme_super --password S3CR37
3
4# Update the default Account User Ref in profile.json:
5fluent profile update my-acme-profile --user acme_super
6
7# Add a new (but existing) Retailer (and User):
8fluent profile update my-acme-profile --retailer fc_sports --id 2 --username fc_sports_admin --password S3CR37
9
10# Update the default Retailer User Ref in retailer.<retailer_ref>.json:
11fluent profile update my-acme-profile --retailer fc_fashion --user fc_fashion_super

Language: plain_text

Name: Command Examples

Description:

Examples of Profile Update Command Usage

Updated Profile Directory:
1/Users/jonsnow/.fluentcommerce/my-acme-profile/
2  profile.json
3  retailer.fc_fashion.json
4  retailer.fc_sports.json
5  user.acme_admin.json
6  user.acme_super.json
7  user.fc_fashion_admin.json
8  user.fc_sports_admin.json

Language: plain_text

Name: Updated Profile Directory

Description:

The updated contents of the Profile Directory

Update
`profile.json`
File:
1{
2  "id": "ACME",
3  "baseUrl": "https://acme.sandbox.api.fluentretail.com",
4  "clientSecret": "abc123-xyz987-s3cr37",
5  "user": "acme_super"
6}

Language: sh

Name: Updated Profile Json

Description:

Updated

`profile.json`
file

Updated
`retailer.fc_fashion.json`
File:
1{
2  "id": "1",
3  "ref": "fc_fashion",
4  "user": "fc_fashion_super"
5}

Language: json

Name: Updated Retailer File

Description:

Updated

`retailer.fc_fashion.json`
file

Note: You would need to add the

`fc_fashion_super`
user file first.

Added
`retailer.fc_sports.json`
File:
1{
2  "id": "2",
3  "ref": "fc_sports",
4  "user": "fc_sports_admin"
5}

Language: json

Name: Added Retailer File

Description:

Added

`retailer.fc_sports.json`
file

Added
`user.acme_super.json`
File:
1{
2  "username": "acme_super",
3  "password": "S3CR37"
4}

Language: json

Name: Added User File

Description:

Added

`user.acme_super.json`
file


`export`

The

`export`
command will export Profile information for sharing with other users or applications. Currently export to Postman Environment File format is supported.

Usage

1fluent profile export <profile_name> [options]

Language: sh

Name: profile export usage

Description:

profile export command usage

Arguments

Argument Name

Description

Example

`profile_name`

The name of the profile to export

`my-acme-profile`

Options

Option Name

Description

Required

Default

Example

`--format`

The format to export to.

Currently only

`postman`
accepted.

 

N/A

`postman`

`--retailer`

The Retailer Ref to include.

This can be provided multiple times.

 ✅

N/A

`fc_fashion`

Example

Let’s assume you will export the

`my-acme-profile`
with the
`fc_fashion`
 Retailer credentials.

Command Example
1fluent profile export my-acme-profile --format postman --retailer fc_fashion

Language: sh

Name: Example Profile Export

Description:

Profile Export Command Example

Postman Environment File
1{
2  "name": "ACME-Env",
3  "values": [
4    {
5      "key": "fluent.account.host",
6      "value": "https://acme.sandbox.api.fluentretail.com",
7      "type": "default",
8      "enabled": true
9    },
10    {
11      "key": "fluent.account.client_id",
12      "value": "ACME",
13      "type": "default",
14      "enabled": true
15    },
16    {
17      "key": "fluent.account.username",
18      "value": "acme_admin",
19      "type": "default",
20      "enabled": true
21    },
22    {
23      "key": "fluent.account.password",
24      "value": "S3CR37",
25      "type": "secret",
26      "enabled": true
27    },
28    {
29      "key": "fluent.account.client_secret",
30      "value": "abc123-xyz987-s3cr37",
31      "type": "secret",
32      "enabled": true
33    },
34    {
35      "key": "fluent.retailer.fc_fashion.id",
36      "value": "1",
37      "type": "default",
38      "enabled": true
39    },
40    {
41      "key": "fluent.retailer.fc_fashion.ref",
42      "value": "fc_fashion",
43      "type": "default",
44      "enabled": true
45    },
46    {
47      "key": "fluent.retailer.fc_fashion.user.username",
48      "value": "fc_fashion_admin",
49      "type": "default",
50      "enabled": true
51    },
52    {
53      "key": "fluent.retailer.fc_fashion.user.password",
54      "value": "S3CR37",
55      "type": "secret",
56      "enabled": true
57    },
58    {
59      "key": "fluent.retailer.current.id",
60      "value": "1",
61      "type": "default",
62      "enabled": true
63    },
64    {
65      "key": "fluent.retailer.current.ref",
66      "value": "fc_fashion",
67      "type": "default",
68      "enabled": true
69    },
70    {
71      "key": "fluent.retailer.current.user.username",
72      "value": "fc_fashion_admin",
73      "type": "default",
74      "enabled": true
75    },
76    {
77      "key": "fluent.retailer.current.user.password",
78      "value": "S3CR37",
79      "type": "secret",
80      "enabled": true
81    }
82  ]
83}

Language: json

Name: Profile Export Example Postman Environment

Description:

Example Postman Environment file generated with the Profile Export Command

Retailer Command

Author:

Lesley Dean

Changed on:

27 Feb 2025

Overview

The

`retailer`
command directs the CLI to perform an action on a Retailer. A Retailer is an entity of an Account, and typically represents a business entity such as a brand or regional entity of a brand.

Key points

  • Subcommands:
    • `create`

`create`

The

`create`
command will create a new Retailer in the Account defined in the provided Profile. It will also create and store a Retailer Profile and Retailer Admin User Profile in the Profile folder.

Usage

1fluent retailer create <retailer_ref> [options]

Language: sh

Name: Retailer Create Usage

Description:

Usage of the Retailer Create command

Arguments

Argument Name

Description

Example

`retailer_ref`

The reference name of the Retailer to create

`fc_fashion`

Options

Option Name

Description

Required

Default

Example

`--profile`

The Profile to create the Retailer on

 

N/A

`my-acme-profile`

`--email`

The Retailer’s Contact Email Address

 

N/A

`fc-fashion@test.com`

`--trading-name`

The Trading Name of the Retailer

N/A

`FC Fashion`

`--region`

The Region of the Retailer

N/A

`AU`

`--phone-number`

The Retailer’s Contact Phone Number

N/A

`+61 2 9999 1234`

`--website`

The Retailer’s website Url

N/A

`https://fcfashion.test.com

Example

Let’s assume you will create a Retailer called

`fc_fashion`
on Account
`ACME`
(identified by the
`my-acme-profile`
).

Command Example
1fluent retailer create fc_fashion --email fc_fashion@test.com --profile my-acme-profile

Language: sh

Name: Retailer Create Command Example

Description:

Example using Retailer Create command

Updated Profile Directory
1/Users/jonsnow/.fluentcommerce/my-acme-profile/
2  profile.json
3  retailer.fc_fashion.json
4  user.acme_admin.json
5  user.fc_fashion_admin.json

Language: plain_text

Name: Updated Profile Directory

Description:

Updated view of the contents of the Profile directory

`retailer.fc_fashion.json`
File
1{
2  "id": "1",
3  "ref": "fc_fashion",
4  "user": "fc_fashion_admin"
5}

Language: json

Name: retailer.fc_fashion.json File

Description:

Example of the retailer.fc_fashion.json file

`user.fc_fashion_admin.json`
File
1{
2  "username": "fc_fashion_admin",
3  "password": "S3CR37"
4}

Language: json

Name: user.fc_fashion_admin.json file

Description:

Example of the user.fc_fashion_admin.json file

Module Command

Author:

Lesley Dean

Changed on:

27 Feb 2025

Overview

The

`module`
command directs the CLI to perform an action on a Module. A Module is a Fluent Package containing Assets which can be installed on an Account.

Key points

  • Subcommands:
    • `create`
    • `describe`
    • `config`
    • `install`

`create`

The

`create`
command will create a new Module using the Fluent Module Template. The resulting directory structure can be used to create an Extension Module or Data Module and can be deployed into an account using the
`module install`
command.

That directory structure can then be checked into the source repository of choice and used within your team for future development.

For more details about the Module structure and assets, read more about modules in the References section below.

This command will:

  • Download the Module template archive
  • Unpack it to the current directory
  • Clean up the downloaded template archive

Usage

1fluent module create

Language: plain_text

Name: Usage of the module create command

Description:

Creating a module with the module create command

Arguments

Argument Name

Description

Example

`template_path`

Optional. The location of the template archive. 

If not specified, defaults to using the latest template from Fluent Downloads.

`./my-module-template.zip`

Options

Option Name

Description

Required

Default

Example

`--base-dir`

Directory to unzip the module template into.


 

`.`


Example

Let’s assume you want to populate a new retailer with some catalogs, workflows and some data. You will first create a new module, then copy in or create the necessary asset files in their directories. For example, create a couple of categories in the file located in

`resources/categories/categories.json`
.

In concrete steps:

  • Create a new directory for the extension module:
    `fluent module create`
  • Create a few categories in
    `resources/categories/categories.json`

`describe`

The

`describe`
command can be used to understand what is contained in a given Module. It will list down the contents of that Module. The asset names can then be used with the  
`module install`
command's
`--include`
or
`--exclude`
options to control which assets or files should be installed or excluded.

For more details about the Module structure and assets, read more in the Fluent Module Specification.

This command will:

  • Download the Module, if it was a remote location or Reference Module
  • If needed, unpack it to the current directory
  • Print out the contained assets, like workflows, settings, rules, etc.
  • Clean up any downloaded archive and any created files

Usage

1fluent module describe order

Language: plain_text

Name: Usage of the module describe command

Description:

Describing a module with the module describe command

Arguments

Argument Name

Description

Example

`module_path`

The Module name, URL, archive filename or path to a Fluent Module directory.

Recognized Module Names are:

`order`
`fulfilment`
`inventory`
`core`

`order`

Options

Option Name

Description

Required

Default

Example

`--module-version`

The version of the module to install. Applies only to Fluent Reference Modules 


 

`latest`

`1.2.3`

`--base-dir`

The base directory to extract the module archive into.


`.tmp`

`.`

Example

Let's assume you want to know the contents of

`order`
module, so that you can pick and choose which workflow to include during the
`install`
step.

Command Example
1fluent module describe order

Language: sh

Name: Module Describe Command Example

Description:

Module Describe Command Example 

This will list the content of the

`order`
module in a table, and the showed content like
`workflows/fc-workflow-order-cc.json`
can be later supplied to
`install`
command's --include option to only install the Click and Collect workflow

`config`

The

`config`
command will inspect the provided Module, and generated a configuration file for the specified Retailer in the users current working directory.

The Configuration file may contain a series of keys and empty values to be populated for the specific Retailer prior to installation.

Not all Modules require configuration.

Usage

1fluent module config <module_path> [options]

Language: sh

Name: Usage of the module config command

Description:

Module Config Command usage

Arguments

Argument Name

Description

Example

`module_path`

The Module name, URL, archive filename or path to a Fluent Module directory.

Recognized Module Names are:

`order`
`fulfilment`
`inventory`
`core`

`order`

Options

Option Name

Description

Required

Default

Example

`--profile`

The Profile to configure the module for

 

N/A

`my-acme-profile`

`--retailer`

The Retailer Reference to configure the module for

 

N/A

`fc-fashion`

`--module-version`

The version of the module to install. Applies only to Fluent Reference Modules 


`latest`

`1.2.3`

`--base-dir`

The base directory to extract the module archive into.


`.tmp`

`.`

Example

Let’s assume you will install the

`order`
Reference Module on the
`fc_fashion`
Retailer on the
`ACME`
Account identified by the
`my-acme-profile`
Profile. The Order Reference Module requires a Configuration file to be provided. This can be generated using the following command:

Command Example
1fluent module config order --retailer fc_fashion --profile my-acme-profile

Language: sh

Name: Module Config Example

Description:

Module Config Command Example

Current Working Directory
1<my_current_working_dir>/
2  module.config.fc_fashion.order.json

Language: plain_text

Name: Current Working Directory

Description:

Example output of the Module Config Command

`module.config.fc_fashion.order.json`
File
1{
2  "default:system.rejected.location.ref": "",
3  "default:inventory.catalogue.ref": "",
4  "default:inventory.retailer.id": "",
5  "default:carrier.ref": "",
6  "default:label.url": "",
7  "workflow:order:cc:network.ref": "",
8  "workflow:order:cc:virtual.catalogue.ref": "",
9  "workflow:order:hd:network.ref": "",
10  "workflow:order:hd:virtual.catalogue.ref": "",
11  "workflow:order:multi:network.ref": "",
12  "workflow:order:multi:virtual.catalogue.ref": ""
13}

Language: json

Name: Example module.config.fc_fashion.order.json file

Description:

Example of the generated Config file of the Order Module

This file should be populated with the relevant values aligned to the specific project / Retailer set up you are implementing. This will ensure that the module workflows and settings assets will be correctly configured with values during installation.


`install`

The

`install`
command will install the Module on the Account and Retailer with the provided configuration.

Usage

1fluent module install <module_path> [options]

Language: sh

Name: Module Install Usage

Description:

Module Install Usage

Arguments

Argument Name

Description

Example

`module_path`

The Module name, URL, archive filename or path to a Fluent Module directory.

Recognized Module Names are:

`order`
`fulfilment`
`inventory`
`core`

`order`

Options

Option Name

Description

Required

Default

Example

`--profile`

The Profile to configure the module for

 

N/A

`my-acme-profile`

`--retailer`

The Retailer Reference to configure the module for

 

N/A

`fc-fashion`

`--config`

The Configuration file containing valid values required by the Module Assets.

The install command will produce an error if the Config is required and not provided. If the Module does not required Config, it will install without Config

*when the module requires a config only

 

N/A

`module.config.fc_fashion.order.json`

`--module-version`

The version of the module to install. Applies only to Fluent Reference Modules 


`latest`

`1.2.3`

`--base-dir`

The base directory to extract the module archive into.


`.tmp`

`.`

`--include`

The Asset(s) to include. This will only install the listed Asset(s).

Use

`fluent module describe`
to get a list of Assets or Asset Files.

Note you can use includes or excludes, but not both at the same time.


N/A

To include an entire set of Assets, e.g. products:

`--include products`

To install only a specific workflow:

`--include workflows/fc-workflow-order-cc.json`

Install multiple Assets, e.g. all plugins and all workflows:

`--include rules workflows`

`--exclude`

The Asset(s) to exclude. This is install all Assets in the module, except the listed Asset(s).

The same format as for

`--include`
applies.


N/A

To install all assets from the module, except the workflows:

`--exclude workflows`

To install all assets, except the Order Multi Workflow:

`--exclude workflows/fc-workflow-order-multi.json`

Example

Continuing from the previous example, let’s assume you will install the

`order`
Reference Module on the
`fc_fashion`
Retailer on the
`ACME`
Account identified by the
`my-acme-profile`
Profile.

Command Example
1fluent module install order --config module.config.fc_fashion.order.json --retailer fc_fashion --profile my-acme-profile

Language: sh

Name: Module Install Command Example

Description:

Module Install Command Example 

This will install all the Assets included in the Module package.


Config Example
1fluent module config https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest --retailer b2c --profile cli-b2c
2
3
4// The config command will downbload the zip file to .tmp folder:
5
6myUser@MacBookPro cli-cust1 % cd .tmp 
7myUser@MacBookPro .tmp % ls -ltr
8total 36496
9-rw-r--r--  1 myUser  staff  2710129  3 Feb 14:32 fc-module-core-1.2.6.zip
10-rw-r--r--  1 myUser  staff  1652432  3 Feb 14:33 fc-module-fulfilment-2.1.0.zip
11-rw-r--r--  1 myUser  staff  9633859  3 Feb 14:37 fc-module-order-1.3.0.zip
12-rw-r--r--  1 myUser  staff  4662083  3 Feb 14:38 fc-module-inventory-2.1.0.zip
13-rw-r--r--  1 myUser  staff    10919  3 Feb 14:45 fcx-module-b2c-sample-data-0.0.2.zip
14drwxr-xr-x  8 myUser  staff      256  3 Feb 14:46 fcx-module-b2c-sample-data-0.0.2
15myUser@MacBookPro .tmp % cd fcx-module-b2c-sample-data-0.0.2 
16myUser@MacBookPro fcx-module-b2c-sample-data-0.0.2 % ls
17CHANGELOG.md		README.md		assets			module.config.json	module.json
18myUser@MacBookPro fcx-module-b2c-sample-data-0.0.2 % cd assets
19myUser@MacBookPro assets % pwd
20/Users/myUser/.fluentcommerce/cli-b2c/.tmp/fcx-module-b2c-sample-data-0.0.2/assets
21myUser@MacBookPro assets % 
22
23

Language: sh

Name: Module config Command Example

Description:

Module config Command Example to download the zip file

Users can configure each JSON file in the assets folder:

No alt provided
1myUser@MacBookPro% pwd
2/Users/myUser/.fluentcommerce/cli-b2c/
3myUser@MacBookPro%fluent module install ./tmp/fcx-module-b2c-sample-data-0.0.2 --retailer b2c --profile cli-b2c
4

Language: sh

Name: Module install Command with the updated assets

Description:

Module install Command with the updated assets. 

Note: ensure to include the file path of the sample data folder.


Lesley Dean

Lesley Dean

Contributors:
Marco Heuer