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,
pushrefuses 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"