CLI¶
flow starts a streamlet project, verifies a blueprint, writes the AnkkaFlow resource a cluster runs,
and requests resets. It is
one native executable with no JVM to install, for macOS (Apple silicon and Intel) and Linux (x64 and
arm64). Homebrew installs it from the tap ankka's CLI ships through; every release also attaches an
archive and a checksum per platform, and Install the tools covers both:
brew install thinkmorestupidless/tap/ankka-flow
flow version
flow version prints the CLI's version and the protocol version it writes, for example
flow 0.1.0, protocol 1.0. A platform outside the four builds the CLI from source;
Build ankka-flow from source covers that build, which behaves the same.
| exit code | meaning |
|---|---|
0 |
success, or --help |
1 |
refused or failed; every problem is on stderr, one per line |
2 |
usage error: an unknown command or option, or a missing argument |
init, verify and generate need no image, no network and no language runtime. reset needs a
kubeconfig.
flow init¶
flow init <name> [--language scala|python] [--dir <directory>] [--package <package>]
Writes a new streamlet project from templates carried inside flow; it needs no network and no copy
of the repository.
| option | default | meaning |
|---|---|---|
<name> |
— | the streamlet's and the pipeline's name |
--language, -l |
scala |
scala or python |
--dir |
<name> |
where to write; it must not exist, or be empty |
--package |
Scala: the name without -; Python: the name with _ for - |
the Scala package (dotted, lower case) or the Python module |
It refuses, writing nothing and exiting 2, with one line per problem on stderr:
| refused | message |
|---|---|
a name that is not 1–63 of [a-z0-9-], or that starts or ends with - |
name '<name>' must be 1-63 of [a-z0-9-], not starting or ending with '-' |
| a name longer than 40 characters | name '<name>' must be at most 40 characters: it becomes the pipeline id |
| a name that does not start with a letter | name '<name>' must start with a letter: it becomes a class, a package and a module |
| a Scala package that is not dotted lower-case identifiers | '<package>' is not a Scala package: … |
| a Python module that is not a lower-case identifier, or is a keyword | '<package>' is not a Python module: … |
| a directory that holds files | <directory> is not empty: flow init writes a new project into an empty or new directory |
a language other than scala or python |
the usage, as for any wrong option |
On success it prints the number of files written and the next commands: change into the directory,
run the tests, check the descriptor, and flow verify blueprint.conf --descriptors flow. It exits 1,
writing nothing, only if a template would leave a {{token}} unreplaced, which the CLI's own tests
rule out.
The project holds:
| Scala | Python | |
|---|---|---|
| the streamlet | src/main/scala/<package>/<Class>.scala |
src/<module>/streamlet.py |
| its entry point | src/main/scala/<package>/Main.scala |
src/<module>/main.py |
| its test | src/test/scala/<package>/<Class>Suite.scala |
tests/test_streamlet.py |
| the build and the image | build.sbt, project/; sbt Docker/publishLocal |
pyproject.toml, Dockerfile |
| the descriptor command | sbt descriptor, sbt descriptorCheck |
uv run descriptor, uv run descriptor --check |
and, for both, flow/descriptor.json, flow/streamlet.conf, blueprint.conf, docker-compose.yml,
k8s/in-cluster.conf, README.md, .gitignore, .github/workflows/ci.yml and the ankka-flow skills
under .claude/skills/. <Class> is the name in UpperCamelCase.
The streamlet has one inlet in and one outlet out, both JSON with the schema name <name>.v1, and
a string parameter greeting (default hello, ankka-flow). It adds "greeting": <greeting> to each
JSON object it reads and emits it with the record's key and headers; a value that is not a JSON object
fails the batch. The blueprint reads the unmanaged topic <name>.in and writes the managed topic out
(<name>.out in Kafka).
Versions follow the flow that wrote the project:
- the Scala project depends on
ankka-flow-sdkatflow's version; - the Python project pins
ankka-flow, and the committed descriptor names its SDK version, at the release's version — or0.0.0from aflowbuilt between releases, the version the SDKs report then; docker-compose.ymlrunsghcr.io/thinkmorestupidless/ankka-flow-sidecaratflow's version, with+written as-(a Docker tag cannot hold+).
A project written by a flow built from source between releases names a version no registry holds:
build it against the repository's SDK, or write it with a released flow.
flow verify¶
flow verify <blueprint.conf> [--descriptors <dir>] [--conf <file>]...
| option | meaning |
|---|---|
<blueprint.conf> |
the blueprint, HOCON; see the blueprint reference |
--descriptors <dir> |
a directory whose *.json files are streamlet descriptors; other files are ignored. Optional when every streamlet is built in (builtin/<name>), whose descriptors the CLI already knows |
--conf <file> |
deploy-time configuration, HOCON; repeatable, later files win; see Configure at deploy time |
It reads and validates every descriptor, parses the blueprint, checks it against the descriptors, and
checks the --conf files against the result. On success it prints
verified: <n> streamlets, <m> topics on stdout. Otherwise it refuses, listing every problem it found in
one pass:
| problem | message |
|---|---|
| the directory is missing or empty | descriptors: '<dir>' is not a directory, descriptors: '<dir>' holds no *.json files |
| a descriptor does not parse or fails validation (a bad name, a port declared twice, a fingerprint that does not match its schema name, an unsupported protocol version) | descriptor <file>: <problem> |
| two descriptors declare one streamlet | 2 descriptors declare streamlet '<name>' |
| the blueprint is not a file, or not HOCON | blueprint: '<path>' is not a file, The blueprint file has an invalid format: … |
| a streamlet names a descriptor nobody declares | Streamlet '<name>' names descriptor '<descriptor>', which no descriptor declares. |
| two streamlets share a name, or a name is illegal | Duplicate streamlet names detected: …, Invalid streamlet name '<name>'. … |
| a port path names nothing | '<path>' does not point to a known streamlet inlet or outlet, please try <suggestion>. |
| a producer is not an outlet, or a consumer is not an inlet | '<path>' is not a valid producer for topic '<id>', must be an outlet. (and the consumer form) |
| an outlet and an inlet on one topic carry different contracts | '<outlet>' (<contract>) is not compatible with '<inlet>' (<contract>). |
a port uses a format other than json |
'<path>' uses format '<format>', which this version does not support; the only contract format is json. |
| an inlet is connected to nothing | Inlet <streamlet>.<port> is not connected. |
| a port is bound to more than one topic | '<path>' is bound to more than one topic: <ids>. |
| an unmanaged topic has producers | Topic '<id>' is not managed but has producers <paths>; the platform only reads topics it does not own. |
| an unmanaged topic names no brokers and no cluster | Topic '<id>' is not managed and names no bootstrap.servers or cluster. |
| an illegal topic or Kafka cluster name | '<name>' is not a valid topic name, …, Invalid Kafka cluster name '<name>'. … |
--conf does not parse |
--conf <file>: <reason> |
--conf names a topic or streamlet the blueprint does not |
overrides name unknown topic '<id>', overrides name unknown streamlet '<name>' |
--conf sets a parameter the descriptor does not declare |
streamlet '<name>': parameter '<key>' is not declared |
| a parameter has no default and no value | streamlet '<name>': parameter '<key>' has no default and no value |
| a parameter's value is not its type | streamlet '<name>': parameter '<key>' = <value> is not a <type> |
replicas is not a number, or is negative |
streamlet '<name>': replicas must be a number, … must not be negative |
An outlet connected to nothing is allowed. It is printed on stderr as a note
(note: Outlet <streamlet>.<port> is not connected.) and does not change the exit code.
A topic with a port of the graph delta contract gets a note too, saying whether it is compacted:
note: Topic '<id>' carries graph deltas and is compacted (cleanup.policy = compact)., or, for a
blueprint that set another policy or a topic that is not managed, what that means for rebuilding the
graph. Blueprint lists the four notes.
flow generate¶
flow generate <blueprint.conf> [--descriptors <dir>] [--conf <file>]...
[--images <file>] [--image <name>=<ref>]...
[--pipeline <id>] [--version <v>] [-n|--namespace <ns>] [-o|--output <file>]
[--delete-managed-topics]
Everything verify does, then it writes the AnkkaFlow resource as YAML, to stdout or to --output
(which prints wrote <file> on stderr). Deploy-time configuration is merged over the blueprint here, so
the resource says exactly what will run; the operator adds only the sidecar image and Kafka cluster
settings.
| option | meaning |
|---|---|
--images <file> |
a HOCON map of streamlet name to image reference |
--image <name>=<ref> |
one streamlet's image; repeatable; wins over --images |
--pipeline <id> |
the pipeline id; default blueprint.name, else the blueprint's file name up to its first . |
--version <v> |
spec.version; default git describe --tags --always --dirty in the blueprint's directory, else unversioned |
-n, --namespace <ns> |
metadata.namespace; without it the resource has none and kubectl uses its current namespace |
-o, --output <file> |
write here instead of stdout |
--delete-managed-topics |
spec.onDelete.managedTopics: Delete: deleting the resource deletes the topics the pipeline created, and their records; without it, Keep |
The resource's name and spec.pipeline are both the pipeline id. On top of verify's problems it
refuses when:
| problem | message |
|---|---|
| a streamlet has no image | Streamlet '<name>' has no image. A built-in streamlet needs none |
| an image is given for a built-in streamlet | Streamlet '<name>' is built in and takes no image. |
an --images file does not parse |
images: <reason> |
an --image is not name=ref |
--image '<value>' is not name=reference |
| the pipeline id is not a DNS label of at most 40 characters | pipeline id '<id>' must be 1-40 of [a-z0-9-], not starting or ending with '-' |
An images file:
router = "ghcr.io/example/cart-router:0.3.1"
sink = "ghcr.io/example/cart-sink:0.3.1"
A typical deployment:
flow generate blueprint.conf --descriptors flow --conf prod.conf \
--image router=registry.example.com/cart-router:1.2 -n shop | kubectl apply -f -
For a managed topic that carries graph deltas and sets no cleanup.policy, generate writes
cleanup.policy: compact into the topic's topicConfig, and prints the same note verify does. Every
other topic is written as the blueprint and --conf say.
See the resource reference for every field generate writes.
flow reset¶
flow reset <pipeline> [--streamlet <name>]... [-n|--namespace <ns>]
Records a request that the named streamlets reread their inputs from the earliest offset. The operator carries it out; see Rebuild from the start.
| option | meaning |
|---|---|
<pipeline> |
the AnkkaFlow's name |
--streamlet <name> |
a streamlet to reset; repeatable; default every streamlet with an inlet |
-n, --namespace <ns> |
the pipeline's namespace; default the kubeconfig's current namespace |
It reads the AnkkaFlow and the pods labelled with its pipeline, then refuses when:
| problem | message |
|---|---|
| Kubernetes cannot be reached | cannot reach Kubernetes: <reason> |
| no such pipeline | no pipeline '<pipeline>' in namespace '<ns>' |
| a named streamlet does not exist, or has no inlets | cannot reset offsets: no streamlet [<name>], … streamlet [<name>] has no inlets, so no consumer groups to reset |
| no streamlet has an inlet | pipeline <pipeline> has no streamlets with inlets to reset |
a target's replicas is not 0, or it still has pods |
cannot reset offsets while streamlets are running: [<name>] is not scaled to 0; [<name>] still has <n> pod(s). Stop them first: … |
Otherwise it writes the annotation flow.ankka.thinkmorestupidless.com/reset-offsets with
{"id":"<uuid>","streamlets":[…]} and prints reset requested for '<pipeline>': <uuid>. An empty
streamlets list means every streamlet with an inlet.
flow mcp¶
flow mcp
Serves a Model Context Protocol server over standard input and output, for a coding agent: flow's
abilities as tools and this documentation as resources. Standard output carries only the protocol;
started at a terminal, it prints a notice on standard error and waits for a client. Work with a coding
agent lists the tools and how to connect a client.
It reads flow.toml from the directory it is started in — the project's root, when Claude Code starts
it — and that file's context and namespace are the only cluster the cluster tools touch:
context = "kind-ankka"
namespace = "greeter"
Without the file, or with either key empty, every cluster tool answers with a refusal saying what to write there, and the tools that need no cluster still work. The kubeconfig's current context is never used.
| tool | hints | does |
|---|---|---|
verify_blueprint |
read-only | what flow verify prints, refusals included |
generate_resource |
read-only | the YAML flow generate writes; nothing is applied |
flow_version |
read-only | what flow version prints |
search_docs, read_doc |
read-only | this version's documentation, also served as ankka-flow://docs/<path> resources |
list_pipelines, get_pipeline, pipeline_logs, pipeline_lag |
read-only, on the named cluster | the namespace's pipelines; one pipeline's status and events; a streamlet's process or sidecar log; consumer lag per inlet partition from each sidecar's metrics |
apply_pipeline |
destructive, on the named cluster | verify, generate and create or update the resource, as flow generate | kubectl apply would |
reset_pipeline |
destructive, on the named cluster | what flow reset requests, with its refusals |
A tool's failure is answered as an error result the agent can read; the session continues.
flow mcp install¶
flow mcp install [--client code|desktop] [--scope user|project] [--dir <project>]
[--command <path>] [--force] [--dry-run]
Tells an MCP client how to start flow mcp.
| option | default | meaning |
|---|---|---|
--client |
code |
code for Claude Code, desktop for Claude Desktop |
--scope |
user |
user: every project, for you, through claude mcp add --scope user; project: a .mcp.json in the project, to commit |
--dir <project> |
. |
the project, for --scope project |
--command <path> |
the first flow on PATH |
the flow Claude Desktop starts; Desktop does not see a shell's PATH, so the entry holds an absolute path, and for the JVM build a JAVA_HOME |
--force |
— | replace an existing ankka-flow entry |
--dry-run |
— | print what would change; change nothing |
Every write merges: other servers and settings in the file are kept in their order, and an existing
server named ankka-flow that differs is left as it is and shown, unless --force. A project written
by flow init already has its .mcp.json, so it needs no install.
It exits 0 when it changed what it said, or had nothing to change, and 1 with the reason on stderr
when it could not: --scope project with --client desktop, Claude Desktop on an operating system
without it, a configuration file that is not valid JSON (left as it is), no flow to name for Desktop,
or a claude command that failed. When claude is not on PATH, --scope user changes nothing and
prints the command to run; that is exit 0.
flow version¶
flow version
Prints the CLI's version and the protocol version its resources carry, as
flow <version>, protocol <major>.<minor>.