The licence tool
stoatflow-licence-tool is a small command-line tool for your StoatFlow licences. It verifies a licence offline with the same code the engine runs, applies a licence to a Kafka cluster's licence registry (that is how renewals reach running applications), shows what the registry counts, and writes the usage reports your licence agreement may ask for. How licensing works is on Licence configuration; this page is the how-to.
Getting the tool
Your Reposilite credentials (the same ones your build uses for StoatFlow artifacts) fetch the fat jar directly; use the version of the StoatFlow your applications run (currently 1.0.0-rc.5):
curl -u customer-<slug>:<token> -O \
"https://maven.stoatflow.io/releases/io/stoatflow/stoatflow-licence-tool/<version>/stoatflow-licence-tool-<version>-all.jar"
java -jar stoatflow-licence-tool-<version>-all.jar --help
Teams that resolve through their build can depend on io.stoatflow:stoatflow-licence-tool:<version>:all.
Connecting to Kafka
Every command but verify and fleet-report (from files) takes:
| Option | Meaning |
|---|---|
--bootstrap-server | the Kafka cluster's bootstrap servers |
--command-config | a properties file of client settings — security.protocol, sasl.*, ssl.* — as Kafka's own tools take it |
--topic | the licence registry topic, default __stoatflow_licence (the history topic is <topic>_history); set it when your applications set stoatflow.licence.registry.topic |
The principal needs, per command: for status, DESCRIBE and READ on the registry topic; for apply, WRITE on it too (and CREATE if it does not exist yet); for report and fleet-report --bootstrap-servers, DESCRIBE and READ on the registry topic (for the licence's terms) and on the history topic.
verify
java -jar stoatflow-licence-tool-all.jar verify licence.sfl1 # a file, `-` for stdin, or the sfl1 string
Prints the licence as JSON — licence id and sequence number, licensee, tier, allowances, standbys, cluster binding, expiry and "expired" — and exits 0. A licence that does not verify is refused with its code (MALFORMED, INVALID_SIGNATURE, UNKNOWN_KEY, KEY_SCOPE) and exit code 1. No network access is used.
apply
java -jar stoatflow-licence-tool-all.jar apply licence.sfl1 --bootstrap-server kafka:9092 \
--command-config client.properties
apply verifies the licence offline, then writes it to the registry topic (creating the topic if it does not exist):
- Running instances of the same licence id switch to it at once when its sequence number is higher than theirs, and log the switch. A renewal ends a restart grace; a trial extension cancels a pending trial stop.
- Instances that start later use it too: the registry's licence wins over a configured one with a lower sequence number — also when the configured one has expired, or does not cover the instance's Kafka cluster or environment class.
- Refused: a licence that does not verify, one that has expired, one bound to other Kafka clusters (applied here, every restart would be refused), and one whose sequence number is not above the one already applied for its id — there is no rollback, also when a newer version of the tool applied that licence with a signing key this version does not hold. The refusal names that key: use the newest tool, and if it says the same, the record is not a StoatFlow licence — re-run
applywith--replace-unverifiableto replace it. A record with a bad signature never blocks one. When runs apply the same licence at once, the highest sequence number stays applied, and the output of a run that lost says so ("applied": false,"superseded": true,restoredSeq); when the check for such a run cannot read the registry after the write, the output says"concurrencyChecked": false, and when applies kept landing until it gave up,"concurrencySettled": false— runstatusto see which licence the registry holds. When the cluster id cannot be read, a licence bound to clusters is applied unchecked, and the output says"clusterChecked": false. - With
stoatflow.licence.source: registry, applications that configure no licence adopt it (see Licence configuration).
A licence applied to one cluster reaches only that cluster's applications: apply it to each cluster.
status
java -jar stoatflow-licence-tool-all.jar status --bootstrap-server kafka:9092 [--licence lic_7Q2…]
Prints, per licence id on the registry topic: the applied licence (or null when none was applied), the live count per environment class — registered, starting, standbys running and counted, against the licensed count and cap — the counted services with their application ids, and the trial ledger entry for a trial. It writes nothing.
An instance counts as live by the brokers' clock — within 90 seconds of the topic's newest record — so the count does not depend on the clock of the machine running the tool ("liveness": "brokers"). When the newest record is older than that 90-second window plus five minutes (about 6.5 minutes) by that machine's clock, no instance is heartbeating and the output says "stale": true. On a registry topic with message.timestamp.type=CreateTime each record is judged by its writer's clock against the tool's ("liveness": "writer-clock").
report
java -jar stoatflow-licence-tool-all.jar report --bootstrap-server kafka:9092 \
--licence lic_7Q2… --from 2026-10-01 --to 2027-09-30 --output usage-acme-2027.json
The usage report of one licence on this cluster for the UTC days --from to --to (default: today), read from the history topic by time window. --licence takes the licence id — its terms then come from the licence applied to the registry, when there is one — or the licence itself (a file or the sfl1 string); an argument that names no file and is not a licence id (lic_…) is a usage error. Application ids and services appear as hashes unless you add --include-app-names. What it contains is described on Licence configuration; a running application serves the same report at GET /licence/usage.
The history read may take two minutes; --timeout gives it more, as an ISO-8601 duration (--timeout PT10M for a year's report over a slow link). A missing history topic is reported at once. registry.brokerClock says whether the history topic carries your brokers' clock (message.timestamp.type=LogAppendTime, as StoatFlow creates it).
{
"format": "stoatflow-usage/1",
"licence": {"lid": "lic_7Q2…", "seq": 3, "licensee": "ACME Corp", "tier": "production",
"allowances": {"production": {"services": 25}}, "standbys": {"free": 1}},
"cluster": {"id": "<Kafka cluster id>"},
"period": {"from": "2026-10-01", "to": "2027-09-30"},
"registry": {"brokerClock": true, "unverifiedHours": 0, "historyGapHours": 0},
"classes": {
"production": {"peakConcurrent": 26, "p95DailyPeak": 24, "avgDailyPeak": 21.3, "distinctServices": 31,
"daysOverLicensed": 2, "standbys": {"peakRunning": 4, "peakCounted": 1}},
"staging": {"peakConcurrent": 22, "distinctServices": 40}
},
"environments": [{"label": "prd-eu", "class": "production", "peak": 14}],
"services": [{"service": "<hash>", "environment": "prd-eu", "class": "production", "applicationIds": ["<hash>"]}],
"daily": [{"date": "2026-10-01", "class": "production", "distinct": 19, "peak": 19, "standbysCounted": 0}],
"engineVersions": {"1.0.3": 18, "1.1.0": 23}
}
The report is yours: read every byte before you send it.
fleet-report
java -jar stoatflow-licence-tool-all.jar fleet-report usage-eu.json usage-us.json usage-apac.json
# or build each cluster's report first:
java -jar stoatflow-licence-tool-all.jar fleet-report --licence lic_7Q2… --from 2026-10-01 --to 2027-09-30 \
--bootstrap-servers kafka-eu-1:9092,kafka-eu-2:9092 --bootstrap-servers kafka-us-1:9092 \
--command-config client.properties
Merges one licence's per-cluster reports into one document (stoatflow-fleet-usage/1): each class's daily total is the sum of each cluster's daily peak — an upper bound, since a service lives in one cluster and clusters may peak at different hours — with its peak, 95th percentile and average over the period, the days over the licensed count, and the list of clusters. Give --bootstrap-servers once per cluster, each with that cluster's bootstrap servers; --timeout applies to each cluster's history read. Reports of different licences or different periods, two of one cluster, or one without a cluster id are refused.
Exit codes
| Code | Meaning |
|---|---|
0 | done; the JSON is on stdout — with report --output, the report is in the file and stdout has a written confirmation (logs go to stderr) |
1 | refused: a licence that does not verify, a sequence number that is not higher, a report of another format |
2 | a usage or connection error |
Production checklist
A go-live checklist for StoatFlow — replica count, licence, probes, metrics, error policies, tuning, and thread safety — each item linking to the canonical page that covers it in full.
Migrating from Kafka Streams
What carries over unchanged when you move a Kafka Streams topology to StoatFlow, what changes operationally, and how to decide between a green-field cutover and a state-carrying migration.