CLI Reference
fluidgrids, from @fluidgrids/cli, manages workflows, triggers and watches runs, and works with credentials, webhooks and scheduled jobs from a terminal or a CI job. It also carries the shared platform commands (workspaces, organisations, tags, files, billing, notifications, support and more).
Install
npm install -g @fluidgrids/cli
# or
bun add -g @fluidgrids/cli
The CLI needs Node.js 24.11 or later (or Bun 1.3.14 or later). Check the install with:
fluidgrids --version
Sign in
The CLI signs you in with the OAuth device-code flow. It never asks for your password.
fluidgrids auth login # prints a URL and a code; approve it in your browser
fluidgrids workspace list
fluidgrids workspace set <id> # selects the workspace and issues the token workspace commands need
fluidgrids auth status
For automation, sign in as an app with fluidgrids auth login --client-credentials --workspace-id <id> (register the app and create its credentials under Developer Portal in the app); for unattended jobs see In CI. fluidgrids auth logout revokes the tokens and clears what is stored.
Command groups
| Group | What it covers |
|---|---|
workflows | List, get, version, create, update, delete, trigger, duplicate, publish, activate, deactivate, archive and import workflows |
runs | List, get, cancel, pause, resume, wait for and read the logs of runs; retry one failed node |
nodes | Browse the node catalog |
credentials | Integration connections: list types, create, attach an API key or basic-auth secret, test, update, delete |
webhooks | Webhook triggers: list, get, create, update, delete, activate, deactivate |
scheduled-jobs | Schedules: list, get, create, update, delete, pause, resume |
dashboard | Summary and usage metrics |
search | Search workflows, runs and nodes |
admin | FluidGrids system information |
auth, workspace, organizations, rbac | Sign-in, workspaces and their members, organisations, roles |
tags, files, groups, conversations, security, integrations, channels, scheduler, export, notifications, support, products, billing, store, devportal, tours | The shared platform modules |
health | ping, and context to print the endpoints and config directory in use |
Run fluidgrids <group> --help for every subcommand and its options.
Examples
# Workflows
fluidgrids workflows list --status ACTIVE
fluidgrids workflows get --key <workflowKey> --wf-version <version>
fluidgrids workflows versions <workflowKey>
fluidgrids workflows create workflow.json # a CreateWorkflowDefinitionInput
fluidgrids workflows activate <definitionId>
fluidgrids workflows duplicate <workflowKey> <version> --new-key <key>
# Trigger a run and follow it
fluidgrids workflows trigger <workflowKey> --wf-version <version> --trigger-node <nodeId> \
--input '{"amount":42}'
fluidgrids runs wait <runId> --timeout 600000
fluidgrids runs logs <runId> --level WARN
fluidgrids runs list --workflow-key <workflowKey> --status FAILED
fluidgrids runs retry-node <runId> <graphNodeId>
fluidgrids runs resume <runId> --payload '{"approved":true}'
# Credentials: create the connection, then attach the secret
fluidgrids credentials types --search stripe
fluidgrids credentials create connection.json # a CreateConnectionInput, no secrets
fluidgrids credentials auth-api-key <connectionId> --api-key-env PROVIDER_KEY
fluidgrids credentials test <connectionId>
# Webhooks and schedules
fluidgrids webhooks list --workflow-key <workflowKey>
fluidgrids webhooks deactivate <id>
fluidgrids scheduled-jobs list --enabled
fluidgrids scheduled-jobs pause <jobId>
Secrets come from a hidden prompt or from the name of an environment variable (--api-key-env, --password-env), never from a flag value, so they do not end up in your shell history. Destructive commands ask for confirmation; pass --force in scripts. Every data command takes -f, --format json|table|yaml, and prints JSON when its output is not a terminal.
Configuration
State lives in ~/.config/fluidgrids-cli/. The token file is readable only by you. The CLI points at production by default; override it with environment variables:
| Variable | Purpose | Default |
|---|---|---|
FLUIDGRIDS_WORKSPACE_ENDPOINT | Workspace gateway | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
FLUIDGRIDS_GLOBAL_ENDPOINT | Global gateway | https://graphql.burdenoff.com/global/graphql |
FLUIDGRIDS_OIDC_ISSUER | Device-code sign-in issuer | https://graphql.burdenoff.com/global |
FLUIDGRIDS_ORIGIN | Product origin, for a gateway other than production or alpha | set automatically |
For alpha, set all three:
export FLUIDGRIDS_WORKSPACE_ENDPOINT=https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
export FLUIDGRIDS_GLOBAL_ENDPOINT=https://alphagraphql.burdenoff.com/global/graphql
export FLUIDGRIDS_OIDC_ISSUER=https://alphagraphql.burdenoff.com/global
fluidgrids health context # confirm the endpoints in use
The workflow commands are product-scoped: the gateway works out the product from the request's Origin. The CLI sends https://app.fluidgrids.ai to the production gateway and https://alphaapp.fluidgrids.ai to the alpha gateway automatically.
In CI
auth login --client-credentials asks for the app's client ID and secret at an interactive prompt, so it suits a one-off sign-in on a machine you are logged in to rather than an unattended job. For a CI job, sign in with the Node SDK's loginWithClientCredentials instead and call the operations you need from a short script; the SDK covers every workflow, run and credential operation the CLI does.
Keep the client secret in your CI system's secret store, never in the repository.