# 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:

```bash
# 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:

```bash
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](https://modelcontextprotocol.io) 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:

```bash
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):

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

Authenticate with ECR (requires the [AWS CLI](https://aws.amazon.com/cli/)):

```bash
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:

```bash
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.

```bash
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.

```bash
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](https://ngrok.com) or similar during development):

```bash
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](../../README.md) file in the root of this monorepo for details on how to deploy packages.

## Support

Please contact robin.summerhill@emu-analytics.com for support with installing, building or deploying packages in this monorepo.
