CLI Reference
The fluidgrids command-line interface for managing workflows, runs, credentials, and more. It is built from source (see Install), not installed from a package registry.
Install
The CLI is not published to npm yet — build it from source. It depends on the Node SDK through a file: reference to a sibling checkout, and Bun copies that dependency at install time, so the SDK must be built before the CLI is installed:
# 1. clone both repos as siblings
git clone https://github.com/algoshred/fluidgrids-sdk-node.git
git clone https://github.com/algoshred/fluidgrids-cli.git
# 2. build the SDK first
cd fluidgrids-sdk-node && bun install && bun run build && cd ..
# 3. install, build, and link the CLI
cd fluidgrids-cli && bun install && bun run build
bun link # exposes the `fluidgrids` command on your PATH
If you installed the CLI before building the SDK you will see Cannot find module '@fluidgrids/sdk'; fix it with rm -rf node_modules/@fluidgrids && bun install && bun run build.
Verify:
fluidgrids --version
Configuration
The CLI resolves its endpoint and credentials from flags, environment variables, or its local config file (in that order of precedence):
| Setting | Flag | Environment variable | Config command |
|---|---|---|---|
| API endpoint | -u, --url | FLUIDGRIDS_API_URL | fluidgrids config set url |
| JWT token | — | FLUIDGRIDS_TOKEN | fluidgrids auth set-token |
| API key | — | FLUIDGRIDS_API_KEY | fluidgrids auth set-key |
The endpoint defaults to the production workspace gateway, https://graphqlworkspaces.burdenoff.com/workspaces/graphql. BURDENOFF_ENV is not read by the CLI — it applies only to the browser and VS Code extensions.
Examples:
# Production (default)
fluidgrids workflows list
# Alpha — per command
fluidgrids workflows list --url https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
# Local dev — via env var
FLUIDGRIDS_API_URL=http://localhost:4003/workspaces/graphql fluidgrids workflows list
# Persist an endpoint to the CLI config
fluidgrids config set url https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
Reference endpoints
| Environment | Workspace gateway |
|---|---|
prod (default) | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
alpha | https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql |
local | http://localhost:4003/workspaces/graphql |
Authentication
# Email / password
fluidgrids auth login USERNAME PASSWORD
# API key
fluidgrids auth set-key YOUR_API_KEY
# Token
fluidgrids auth set-token YOUR_TOKEN
# Status
fluidgrids auth status
# Sign out (clears stored credentials)
fluidgrids auth logout
API keys are issued from the Developer Portal under API Keys (/devportal/api-keys). There is no OAuth device-code flow.
Command groups
The CLI registers 13 command groups:
| Group | What |
|---|---|
auth | Authentication (login, set-key, set-token, status, logout) |
workflows | Workflow CRUD, versioning, and triggering |
runs | Run monitoring and control |
nodes | Node catalog browsing (list, get, categories) |
credentials | Credential management |
webhooks | Webhook management |
scheduled-jobs | Scheduled (cron) job management |
events | Event definitions and event triggers |
dashboard | Execution stats and dashboards |
search | Cross-resource search |
admin | Administrative operations |
health | Service health checks |
config | CLI local settings (including config set url) |
Common examples
# Workflows
fluidgrids workflows list
fluidgrids workflows get WORKFLOW_ID
fluidgrids workflows trigger WORKFLOW_ID
# Runs
fluidgrids runs list
fluidgrids runs get RUN_ID
fluidgrids runs cancel RUN_ID
# Nodes (browse the catalog)
fluidgrids nodes list
fluidgrids nodes categories
# Credentials
fluidgrids credentials list
# Webhooks & scheduled jobs
fluidgrids webhooks list
fluidgrids scheduled-jobs list
# Config
fluidgrids config show
fluidgrids config set url https://graphqlworkspaces.burdenoff.com/workspaces/graphql
Development
git clone https://github.com/algoshred/fluidgrids-cli.git
cd fluidgrids-cli
bun install
bun run dev -- --help
bun run test
bun run test:coverage
bun run sanity
Source
- Repository:
github.com/algoshred/fluidgrids-cli - Distribution: build from source (not published to npm yet)