Fluent Commerce Logo
Docs

Fluent CLI in Automation

Essential knowledgeCore knowledge to understand Fluent Commerce

Changed on:

9 Nov 2026

Overview

[Warning: empty required content area]

Key points

[Warning: empty required content area]
The Fluent CLI builds profiles, configures and installs modules, and reads back account state. In a pipeline it needs three things that interactive use does not: a pinned version, non-interactive authentication, and a reliable failure signal.

Install a pinned version

Pin the CLI and Node to exact versions in one script that every step runs. Floating versions (`latest`, `22.x`) make an old green build impossible to reproduce.Upgrade the CLI deliberately, in its own change, and re-run the pipeline. The error wrapper below matches CLI log messages, so re-check it after every upgrade.

Profiles

A profile holds the account admin credentials plus one entry per retailer. Retailer-scoped commands (`module install -r <ref>`) authenticate as that retailer's user, so you must add every retailer to the profile before installing.CI runners are discarded after each run, so recreate the profile from scratch every time under a fixed name such as `cicd`. Never restore one from a cache.
Credentials
Supply every credential through secured deployment variables, scoped to the Bitbucket deployment environment (`ACMEDEV`, `ACMEUAT`, ...). The same pipeline then targets a different account simply by running under a different deployment.
VariableScope
`FLUENT_ACCOUNT_ID`, `FLUENT_BASE_URL`Account
`FLUENT_USERNAME`, `FLUENT_PASSWORD`, `FLUENT_CLIENT_SECRET`Account admin (secured)
`FLUENT_RETAILERS`Retailer refs for this run, space- or comma-separated
`FLUENT_RETAILER_<REF>_ID`Per retailer
`FLUENT_RETAILER_<REF>_USERNAME`, `FLUENT_RETAILER_<REF>_PASSWORD`Per retailer (secured)
Use a dedicated integration user per environment with the smallest set of permissions the install needs. Don't reuse a person's login.
Sample: profile.sh
The script checks every required variable before calling the CLI and reports all missing ones in one go, so one run surfaces every gap. It also detects a value that is still a literal `$NAME` reference. That happens when a step is missing its `deployment:` and therefore never received the variables, and the CLI otherwise fails much later with an opaque 401. The script reports variable names only and never prints values.Extend the per-retailer loop to confirm that every reference module named in `cicd/configs/` appears in `fluent module list` output, so a missing base module is caught before anything is installed.

Catching errors the CLI logs but does not exit on

Some CLI operations log an error and still exit with status 0, for example a workflow that fails validation, a plugin upload that is rejected, or a GraphQL error during a settings upsert. A pipeline that relies on the exit code alone will report these deploys as green.Wrap every CLI call in a script that:
  • captures stdout as well as stderr (the CLI logs to stdout),
  • strips ANSI colour codes, which are present even without a TTY,
  • scans the output for known error patterns and fails if any appear,
  • writes one log file per invocation so it can be kept as a pipeline artifact.
The patterns above were checked against one CLI version. Log messages are not a stable API, so re-check the list against the CLI release notes or source whenever you upgrade.
Readable error payloads
By default the CLI prints nested API error bodies as `{ errors: [Array] }`. Preloading a small Node script raises `util.inspect` limits so the log shows the actual error entries. It only changes how errors are printed, never what the CLI does.