Flo.w CLI

The Flo.w CLI (flow-engine-cli) is a command line interface for working with Flo.w Engine via its REST API. It provides developers with tools to work with datasets, pipelines and other Flo.w resources.

Setup and build

After cloning the repository, follow the instructions below to set up your development environment:

# Install dependencies
npm install

# Build project
npm run build

Running and debugging

The built CLI tool will be located in the dist/ folder. To run the CLI, use the following command:

node dist/index.js <commands> [options]

Note that this is equivalent to using flow <commands> [options] when the package is installed globally on an end-developers machine.

To debug the CLI during development, open a JavaScript debug terminal in VSCode (CMD-SHIFT-P and search for 'debug: ja')and run the CLI as above in the terminal. The debugger will attach to the running process and breakpoints can be set directly in the source code.

MCP server (Docker)

The mcp command starts a Model Context Protocol server that exposes Flow Engine resources and tools to AI agents such as Claude.

Building the image

The build context must be the repository root so both flow-engine-client and flow-engine-cli are available:

docker build -f packages/flow-engine-cli/Dockerfile -t flow-mcp .

Multi-architecture build

To build and push an image for both linux/amd64 and linux/arm64, you need a docker-container buildx builder. Create one and set it as the default (one-time setup):

docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

Authenticate with ECR (requires the AWS CLI):

aws ecr get-login-password --region eu-west-1 | \
  docker login --username AWS --password-stdin 809728736372.dkr.ecr.eu-west-1.amazonaws.com

Then build and push:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file packages/flow-engine-cli/Dockerfile \
  --tag <registry>/<image>:<tag> \
  --push \
  .

The --push flag is required — multi-platform images cannot be loaded into the local Docker daemon, only pushed to a registry.

Running the server

Simple — baked-in API key (easiest)

Suitable for a private or single-user deployment. The API key is supplied once at startup and applies to every request.

docker run -d -p 3000:3000 \
  -e FLOW_API_KEY=<your-api-key> \
  flow-mcp

Configure your MCP client to connect to http://localhost:3000/mcp (no Authorization header required).

Client auth — per-request Bearer token

Each MCP client request must include an Authorization: Bearer <api-key> header. Use this when multiple users share a single server instance and each has their own API key.

docker run -d -p 3000:3000 \
  -e FLOW_CLIENT_AUTH=true \
  flow-mcp

OAuth 2.0 — browser-based authorisation for claude.ai

Enables the full OAuth 2.0 authorisation code flow so that web-based MCP clients (e.g. claude.ai connectors) can obtain a token without needing to supply a Bearer header manually. The user is redirected to a form where they enter their Flow API key once; subsequent requests use the issued token.

Requires a publicly reachable URL (use ngrok or similar during development):

docker run -d -p 3000:3000 \
  -e FLOW_OAUTH=true \
  -e FLOW_ISSUER_URL=https://<your-public-hostname> \
  flow-mcp

Point your MCP client at https://<your-public-hostname>/mcp.

Configuration reference

All options can be set via environment variables (prefix FLOW_) or passed as CLI flags.

| Variable | Flag | Default | Description | |---|---|---|---| | FLOW_API_KEY | -k / --api-key | — | Flow Engine API key. Required when FLOW_CLIENT_AUTH=false. | | FLOW_TRANSPORT | --transport | http | http or stdio. | | FLOW_PORT | --port | 3000 | HTTP listen port. | | FLOW_BIND | --bind | 0.0.0.0 | Network interface to bind to. | | FLOW_PATH | --path | /mcp | URL path for the MCP endpoint. | | FLOW_CLIENT_AUTH | --client-auth | false | Require Authorization: Bearer <api-key> on each request. | | FLOW_OAUTH | --oauth | false | Enable OAuth 2.0 authorisation server. Implies --client-auth. | | FLOW_ISSUER_URL | --issuer-url | — | Public base URL of this server. Required when FLOW_OAUTH=true. | | FLOW_HOST | --host | https://flow.emu-analytics.net | Flow Engine base URL. |

Deployment

See the README.md file in the root of this monorepo for details on how to deploy packages.

Support

Please contact [email protected] for support with installing, building or deploying packages in this monorepo.