Skip to main content

The CLI for workflows as code

The fluidgrids CLI (npm install -g @fluidgrids/cli, Node.js 24.11 or later) moves workflows between a project and your workspace. See the CLI reference for signing in and the other commands.

Create a project​

mkdir my-automations && cd my-automations
fluidgrids init --lang ts # or --lang py

init signs you in if needed, writes the project files and generates the typed node clients:

my-automations/
fluidgrids.config.json language and workspace
package.json @fluidgrids/workflows and @fluidgrids/cli (TypeScript)
pyproject.toml fluidgrids-workflows (Python)
.fluidgrids/nodes.ts typed node clients (commit this file)
workflows/<key>.ts one file per workflow, with <key>.layout.json
lock.json registry snapshot, node versions, SDK version, pulled versions

Pass --workspace <id> to tie the project to one workspace. The project then refuses to run against any other.

Python projects need Python 3.11 or later with the fluidgrids-workflows package.

Everyday commands​

fluidgrids codegen # regenerate .fluidgrids/nodes.ts from the workspace's nodes
fluidgrids pull lead-enrichment # export a workflow into workflows/lead-enrichment.ts
fluidgrids pull --as py # every tracked workflow as Python
fluidgrids pull --check # print the fidelity report; exit 1 if an export is lossy
fluidgrids validate --strict # check the definitions, including the strict rules
fluidgrids diff --against active # what differs from the active version
fluidgrids push --dry-run # what a push would change
fluidgrids push -m "Route big leads" # a new version for every workflow whose definition changed
fluidgrids import workflows/new-flow.ts # create a new workflow from a file
fluidgrids interface lead-enrichment # the typed interface of the active version
  • Push builds the whole project once, validates every workflow, and creates a version only for workflows whose definition changed. A key that is new to the workspace is created as a draft.
  • If a workflow got a newer version in the workspace after you pulled it, for example from a canvas edit, push refuses rather than silently undo that change. Pull again and reapply your edit, or pass --force.
  • Connections are written by name. A name that does not resolve in the workspace stops the push before anything is written, with the names to create.

Durable functions​

A project with durable functions also has an activities/ folder for the code they import.

fluidgrids runs start approvals --input '{"orderId": 7}' --wait
fluidgrids runs describe <runId> # function, build, history length, failing task
fluidgrids history <runId> --out run.history.json
fluidgrids signal <runId> approve --payload '{"by":"ana"}'
fluidgrids runs stack <runId> # where the code is waiting
fluidgrids runs cancel <runId> # ask the code to cancel
fluidgrids runs terminate <runId> --reason stuck
fluidgrids replay run.history.json --isolate
fluidgrids test --replay histories/
fluidgrids push --hotfix v3 --replay-sample 20
fluidgrids versions list approvals # versions with the code bundle each one runs

push uploads the code bundle once and links it to each new version; the bundle a push uploads is also written to .fluidgrids/build/, which init adds to .gitignore.

Workers, run control and schedules​

fluidgrids queues create payments # a self-hosted task queue
fluidgrids workers tokens create payments-prod --queue payments
fluidgrids worker run --queue payments --activities activities/index.ts
fluidgrids dev # a temporary queue, token and worker
fluidgrids runs query <runId> status
fluidgrids runs update <runId> addItem --args '{"sku":"a"}'
fluidgrids runs reset <runId> --to last-clean-task
fluidgrids activities pause <runId> --all --reason 'vendor down'
fluidgrids runs batch signal --key approvals --status running --signal nudge --reason resend --dry-run
fluidgrids search-attributes create customerId --type keyword
fluidgrids schedules describe nightly-restock tick
fluidgrids deploy approvals --env staging

Run-scoped commands take a run id, or --workflow-id <id> --key <workflowKey> for the latest run of a workflow id. Destructive commands ask for confirmation; pass --force in scripts. See Self-hosted workers, Run control, Search attributes and Schedules.

In CI​

Use a workspace token instead of an interactive sign-in:

export FLUIDGRIDS_TOKEN=… # from your secret store
export FLUIDGRIDS_WORKSPACE_ID=…
fluidgrids validate --strict
fluidgrids test
fluidgrids diff --exit-code # fail when the workspace has drifted from the repository
fluidgrids push -m "$COMMIT_MESSAGE"

Next steps​