Skip to content

felixctl Reference

Every felixctl command and flag. This page is generated from the command definitions, and felixctl help <command> prints the same text. For installing felixctl, setting up a context and a first session, see felixctl.

Publish and subscribe to streams, read and watch caches, see where shards live, list what the control plane knows, steer placement and run benchmarks. It is the one operator command line: data and controlplane migrate run the broker’s and the control plane’s own tools on the host that holds their data.

Connection settings come from a named context (see felixctl context), overridden by FELIX_* environment variables, overridden by flags.

Examples:

Terminal window
felixctl context add local --brokers 127.0.0.1:5000 --tenant t1 --token-file token.jwt
felixctl pub orders 'hello'
felixctl sub orders --from earliest --count 10
felixctl stream ls --json
Command Summary
felixctl context Manage named connection profiles
felixctl pub Publish messages to a stream
felixctl sub Read messages from a stream
felixctl cache Read, write and watch cache keys, or manage caches
felixctl topology Show a stream’s or cache’s shards, owners and brokers
felixctl group Create, inspect and move consumer groups; claim and settle records
felixctl counter Read and add to counters
felixctl tenant Create, list, inspect and delete tenants (control plane)
felixctl namespace Create, list, inspect and delete namespaces (control plane)
felixctl stream Create, change, list, inspect and delete streams (control plane)
felixctl node List, inspect, drain and deregister brokers (control plane)
felixctl shard List shard assignments and move shards (control plane)
felixctl placement See what placement will do, and pause or resume its moves (control plane)
felixctl features List fleet features and finalize them (control plane)
felixctl backup-point Record every shard’s committed offsets as a backup point (control plane)
felixctl rbac List, grant and revoke RBAC policies and role assignments (control plane)
felixctl inspect Look at a cluster’s live state, read-only (operators)
felixctl data Inspect and restore a broker’s data directory (runs felix-broker)
felixctl controlplane Run control-plane maintenance tools (runs felix-controlplane)
felixctl bench Run a load test against the cluster
felixctl completions Print a shell completion script

These flags apply to every command. Each connection flag overrides the environment variable named in its help, which overrides the current context.

Option Value Default Description
--context <NAME> - Context to use instead of the current one [env: FELIX_CONTEXT]
--config <PATH> - Config file holding the contexts [env: FELIX_CLI_CONFIG] [default: the platform config directory, e.g. ~/.config/felixctl/config.toml]
--brokers <ADDRS> - Broker addresses, host:port, comma-separated [env: FELIX_BROKERS]
--controlplane-url <URL> - Control-plane base URL [env: FELIX_CONTROLPLANE_URL]
--tenant <ID> - Tenant to act as [env: FELIX_AUTH_TENANT]
-n, --namespace <NS> - Namespace [env: FELIX_NAMESPACE] [default: default]
--token <JWT> - Broker token [env: FELIX_AUTH_TOKEN]
--token-file <PATH> - File holding the broker token [env: FELIX_AUTH_TOKEN_FILE]
--controlplane-token <JWT> - Control-plane token [env: FELIX_CONTROLPLANE_TOKEN]
--controlplane-token-file <PATH> - File holding the control-plane token [env: FELIX_CONTROLPLANE_TOKEN_FILE]
--ca-file <PATH> - PEM bundle the broker certificates are checked against [env: FELIX_CA_FILE] [default: the platform trust store]
--client-cert-file <PATH> - PEM client certificate chain to present to brokers [env: FELIX_CLIENT_CERT_FILE]
--client-key-file <PATH> - PEM private key for –client-cert-file [env: FELIX_CLIENT_KEY_FILE]
--controlplane-ca-file <PATH> - PEM bundle an https control plane is checked against [env: FELIX_CONTROLPLANE_CA] [default: the platform trust store]
--server-name <NAME> - TLS server name sent to brokers [env: FELIX_SERVER_NAME] [default: the first broker’s host name, or localhost for an IP address]
--alpn - - Offer the felix/1 ALPN, which a broker with FELIX_TLS_REQUIRE_ALPN needs. Brokers from before ALPN support refuse it
Option Value Default Description
--json - - Print JSON instead of human-readable output. Errors go to stderr as JSON too

Scripts can branch on the exit status. Each value means one thing.

Status Meaning
0 Success.
1 Anything not covered below.
2 Bad arguments, or settings missing or unreadable.
3 No broker or control plane could be reached.
4 A broker or the control plane refused the request.
5 The key, resource or context does not exist.
6 A write may have been applied: the broker stopped waiting for it.

With --json, errors go to stderr as a JSON object holding error and exit.

Manage named connection profiles.

A context holds the broker addresses, control-plane URL, tenant, namespace, tokens and TLS files for one cluster, so commands do not need them as flags. Contexts live in a TOML file in the platform config directory; –config or FELIX_CLI_CONFIG points elsewhere.

felixctl context [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl context add local --brokers 127.0.0.1:5000 --tenant t1 --token-file token.jwt
felixctl context ls
felixctl context use prod
felixctl context rm local

Save the connection flags given on this command line as a new context. Only flags are saved; environment variables are not. The first context added becomes the current one.

felixctl context add [OPTIONS] <NAME>
Argument Required Description
NAME yes Name of the context
Option Value Default Description
--use - - Make it the current context
--replace - - Replace a context that already has this name

Examples:

Terminal window
felixctl context add local --brokers 127.0.0.1:5000 --tenant t1 \
--token-file token.jwt --ca-file broker-cert.pem
felixctl context add prod --brokers a.example:5000,b.example:5000 \
--controlplane-url https://cp.example --tenant acme --use

Make NAME the context every command uses unless –context or FELIX_CONTEXT says otherwise.

felixctl context use [OPTIONS] <NAME>
Argument Required Description
NAME yes Name of the context

Examples:

Terminal window
felixctl context use prod

List the saved contexts. The current one is marked with *.

felixctl context ls [OPTIONS]

Examples:

Terminal window
felixctl context ls
felixctl context ls --json

Delete a saved context. Deleting the current one leaves no context current.

felixctl context rm [OPTIONS] <NAME>
Argument Required Description
NAME yes Name of the context

Examples:

Terminal window
felixctl context rm local

Publish messages to a stream.

The message comes from the DATA argument, from –file, or from stdin. Stdin is read one message per line unless –whole is given. By default each publish waits for the broker’s acknowledgement and reports the record’s offset when the ack carries one. A broker that owns the shard and acks on enqueue (FELIX_ACK_ON_COMMIT=0, or an in-memory stream) answers before the record has an offset. An –idempotent publish is always answered after the write.

felixctl pub [OPTIONS] <STREAM> [DATA]
Argument Required Description
STREAM yes Stream to publish to
DATA no The message. Without it, –file or stdin is read
Option Value Default Description
--file <PATH> - Publish this file’s contents as one message
--whole - - Read all of stdin as one message instead of one per line
--key <KEY> - Routing key; records with the same key go to the same shard
--count <N> 1 Publish each message this many times
--ack <MODE> message What to wait for: message waits for each acknowledgement, none sends without one. One of message, none.
--idempotent - - Publish through an idempotent producer, so a re-send after a reconnect cannot duplicate a record. Always acknowledged

Examples:

Terminal window
felixctl pub orders 'hello'
felixctl pub orders --key customer-42 '{"total": 10}'
tail -f app.log | felixctl pub logs
felixctl pub images --file cat.png --idempotent

Read messages from a stream and print them.

Starts at the live tail unless –from says otherwise. Without –shard, every shard of the stream is read and merged. Runs until –count messages have arrived or it is interrupted.

felixctl sub [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream to read
Option Value Default Description
--from <POSITION> latest Where to start: latest, earliest, or a log offset
--shard <N> - Read only this shard
--count <N> - Stop after this many messages
--format <FORMAT> raw How to print each message. –json is the same as –format json. One of raw, offsets, json.

Examples:

Terminal window
felixctl sub orders
felixctl sub orders --from earliest --count 10
felixctl sub orders --shard 2 --from 1500 --format offsets
felixctl sub orders --json | jq .payload

Read, write and watch cache keys, or create, change, list, inspect and delete caches.

get, put, del and watch go to the brokers. ls, info, create, set and rm go to the control plane.

felixctl cache [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl cache put sessions user-1 'logged-in' --ttl-ms 60000
felixctl cache get sessions user-1
felixctl cache watch sessions --prefix user-
felixctl cache create sessions --shards 4
felixctl cache ls

Print a key’s value as stored. Exits with status 5 when the key is not set.

felixctl cache get [OPTIONS] <CACHE> <KEY>
Argument Required Description
CACHE yes Cache name
KEY yes Key to read

Examples:

Terminal window
felixctl cache get sessions user-1
felixctl cache get sessions user-1 --json

Set a key to VALUE, to the contents of –file, or to all of stdin.

felixctl cache put [OPTIONS] <CACHE> <KEY> [VALUE]
Argument Required Description
CACHE yes Cache name
KEY yes Key to set
VALUE no The value. Without it, –file or stdin is read
Option Value Default Description
--file <PATH> - Use this file’s contents as the value
--ttl-ms <MS> - Expire the key after this many milliseconds [default: never]

Examples:

Terminal window
felixctl cache put sessions user-1 'logged-in'
felixctl cache put sessions user-1 'logged-in' --ttl-ms 60000
felixctl cache put config app --file app.json

Delete a key. Deleting a key that is not set succeeds.

felixctl cache del [OPTIONS] <CACHE> <KEY>
Argument Required Description
CACHE yes Cache name
KEY yes Key to delete

Examples:

Terminal window
felixctl cache del sessions user-1

Print changes to one key (–key) or to every key under a prefix (–prefix, default every key) as they happen. A prefix watch covers every shard of the cache. With –retained, the current values are printed first.

felixctl cache watch [OPTIONS] <CACHE>
Argument Required Description
CACHE yes Cache name
Option Value Default Description
--key <KEY> - Watch only this key
--prefix <PREFIX> - Watch keys starting with this prefix [default: every key]
--retained - - Print each matching key’s current value before live changes
--from <OFFSET> - Resume a key watch at this cache-log offset
--count <N> - Stop after this many changes

Examples:

Terminal window
felixctl cache watch sessions
felixctl cache watch sessions --key user-1
felixctl cache watch sessions --prefix user- --retained --count 100

List the caches of the current tenant and namespace.

felixctl cache ls [OPTIONS]

Examples:

Terminal window
felixctl cache ls
felixctl cache ls -n payments

Show a cache’s shard count, replication factor and consistency.

felixctl cache info [OPTIONS] <CACHE>
Argument Required Description
CACHE yes Cache name

Examples:

Terminal window
felixctl cache info sessions

Create a cache in the current tenant and namespace. Creating one that already exists with the same settings succeeds; with different settings it is refused.

felixctl cache create [OPTIONS] <CACHE>
Argument Required Description
CACHE yes Cache name
Option Value Default Description
--display-name <TEXT> - Display name [default: the cache name]
--shards <N> 1 Shards to split the keyspace across
--replication <N> 1 Brokers holding a copy of each shard, the leader included
--consistency <LEVEL> leader quorum acknowledges a write once a majority of the shard’s copies hold it. One of leader, quorum.

Examples:

Terminal window
felixctl cache create sessions
felixctl cache create sessions --shards 4 --replication 3 --consistency quorum

Change a cache’s display name, the only setting that can change after creation, and print what changed.

felixctl cache set [OPTIONS] --display-name <TEXT> <CACHE>
Argument Required Description
CACHE yes Cache name
Option Value Default Description
--display-name <TEXT> - New display name

Examples:

Terminal window
felixctl cache set sessions --display-name 'Login sessions'

Delete a cache and every key in it. Asks first on a terminal; elsewhere it needs –yes.

felixctl cache rm [OPTIONS] <CACHE>
Argument Required Description
CACHE yes Cache name
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl cache rm sessions
felixctl cache rm sessions --yes

Show where a stream or cache lives: its shard count, the broker that leads each shard, and the brokers clients can reach.

The shard count and brokers come from a broker. Owners come from the control plane, so they are shown only when a control-plane URL is configured.

felixctl topology [OPTIONS] <NAME>
Argument Required Description
NAME yes Stream (or, with –cache, cache) name
Option Value Default Description
--cache - - NAME is a cache, not a stream

Examples:

Terminal window
felixctl topology orders
felixctl topology sessions --cache
felixctl topology orders --json

Work with consumer groups: create, describe, seek and delete them, claim records with poll, and settle them with ack, nack, extend and dead-letters.

A group keeps a cursor on each shard of its stream, with that shard’s leader. A record is named by its claim, SHARD:OFFSET, which poll prints with the delivery attempt added.

felixctl group [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl group create orders billing --from earliest
felixctl group poll orders billing --max 5
felixctl group ack orders billing 0:15:1
felixctl group describe orders billing

Create GROUP on every shard of STREAM, or on –shard, so that its first poll begins at –from instead of the beginning of the log. A shard where the group already exists is left where it is. Needs the group.manage permission.

felixctl group create [OPTIONS] <STREAM> <GROUP>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
Option Value Default Description
--shard <N> - Only this shard [default: every shard]
--from <POSITION> latest Where the group starts: latest, earliest, or an offset (with –shard, or on a single-shard stream)

Examples:

Terminal window
felixctl group create orders billing
felixctl group create orders billing --from earliest
felixctl group create orders billing --shard 2 --from 1500

Show, for each shard, the offset GROUP has finished up to, the shard’s tail, the lag between them, records handed out and not settled, records owed again, and dead letters. In-flight and owed counts are the leader’s memory and start from zero after a leader change.

felixctl group describe [OPTIONS] <STREAM> <GROUP>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
Option Value Default Description
--shard <N> - Only this shard [default: every shard]

Examples:

Terminal window
felixctl group describe orders billing
felixctl group describe orders billing --shard 0 --json

Move GROUP’s cursor on every shard, or on –shard, to POSITION. Records the group had handed out are void and are delivered again from the new position. Dead letters are kept. Moving the cursor backwards replays finished records, so it asks first on a terminal and needs –yes elsewhere. Needs the group.manage permission.

felixctl group seek [OPTIONS] <STREAM> <GROUP> <POSITION>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
POSITION yes Where to move to: latest, earliest, or an offset (with –shard, or on a single-shard stream)
Option Value Default Description
--shard <N> - Only this shard [default: every shard]
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl group seek orders billing latest
felixctl group seek orders billing earliest --yes
felixctl group seek orders billing 1500 --shard 2

Delete GROUP on every shard, or on –shard: its cursor, its dead letters and the records it has handed out. A consumer that polls it again starts afresh. Asks first on a terminal; elsewhere it needs –yes. Needs the group.manage permission.

felixctl group rm [OPTIONS] <STREAM> <GROUP>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
Option Value Default Description
--shard <N> - Only this shard [default: every shard]
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl group rm orders billing
felixctl group rm orders billing --yes

Claim up to –max records for GROUP and print each with its claim, SHARD:OFFSET:ATTEMPTS, which ack, nack, extend and dead-letters add take. Without –shard each shard is asked in turn until –max records are claimed. A claim not settled is handed out again once it lapses.

felixctl group poll [OPTIONS] <STREAM> <GROUP>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
Option Value Default Description
--shard <N> - Only this shard [default: every shard]
--max <N> 10 Most records to claim
--wait-ms <MS> 0 How long the broker may wait for records on each shard it is asked
--visibility-ms <MS> - How long the claims stand [default: the broker’s visibility timeout]

Examples:

Terminal window
felixctl group poll orders billing
felixctl group poll orders billing --max 100 --wait-ms 5000
felixctl group poll orders billing --shard 1 --visibility-ms 60000 --json

Finish each claimed record. Claims are acted on in order; one that fails stops the rest.

felixctl group ack [OPTIONS] <STREAM> <GROUP> <CLAIM>...
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes Records, as SHARD:OFFSET or the SHARD:OFFSET:ATTEMPTS poll prints

Examples:

Terminal window
felixctl group ack orders billing 0:15:1
felixctl group ack orders billing 0:15 0:16 1:4

Hand each claimed record back to the group, to be delivered again at once, or after –delay-ms. A claim given as SHARD:OFFSET:ATTEMPTS is refused once that delivery’s claim has lapsed or the record has gone out again.

felixctl group nack [OPTIONS] <STREAM> <GROUP> <CLAIM>...
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes Records, as SHARD:OFFSET or the SHARD:OFFSET:ATTEMPTS poll prints
Option Value Default Description
--delay-ms <MS> - Deliver the records again only after this long

Examples:

Terminal window
felixctl group nack orders billing 0:15:1
felixctl group nack orders billing 0:15:1 --delay-ms 30000

Keep the claim on a record standing for –for-ms from now, for a consumer still working on it. The claim needs its attempt count, as poll prints it: the broker refuses an extension for a record that has been handed out again since. The broker may cap the time; the answer says how long the claim now stands.

felixctl group extend [OPTIONS] --for-ms <MS> <STREAM> <GROUP> <CLAIM>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes The claim, SHARD:OFFSET:ATTEMPTS
Option Value Default Description
--for-ms <MS> - How long the claim should stand from now

Examples:

Terminal window
felixctl group extend orders billing 0:15:1 --for-ms 60000

Dead letters are records a group gave up on. The records stay in the log; the group keeps a list of their offsets.

felixctl group dead-letters [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl group dead-letters ls orders billing
felixctl group dead-letters redrive orders billing 0:15

List the dead letters of GROUP on every shard, or on –shard, as claims that redrive and discard take.

felixctl group dead-letters ls [OPTIONS] <STREAM> <GROUP>
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
Option Value Default Description
--shard <N> - Only this shard [default: every shard]

Examples:

Terminal window
felixctl group dead-letters ls orders billing
felixctl group dead-letters ls orders billing --shard 0 --json

Give up on each claimed record: finish it and list it as a dead letter, as the group does once a record runs out of attempts.

felixctl group dead-letters add [OPTIONS] <STREAM> <GROUP> <CLAIM>...
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes Records, as SHARD:OFFSET or the SHARD:OFFSET:ATTEMPTS poll prints

Examples:

Terminal window
felixctl group dead-letters add orders billing 0:15

Deliver each dead letter again, its attempt count reset. The group’s cursor does not move.

felixctl group dead-letters redrive [OPTIONS] <STREAM> <GROUP> <CLAIM>...
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes Records, as SHARD:OFFSET or the SHARD:OFFSET:ATTEMPTS poll prints

Examples:

Terminal window
felixctl group dead-letters redrive orders billing 0:15 1:4

Drop each dead letter from the group’s list. The record stays in the log, but nothing records that it failed any more. Asks first on a terminal; elsewhere it needs –yes.

felixctl group dead-letters discard [OPTIONS] <STREAM> <GROUP> <CLAIM>...
Argument Required Description
STREAM yes Stream the group reads
GROUP yes Group name
CLAIM yes Records, as SHARD:OFFSET or the SHARD:OFFSET:ATTEMPTS poll prints
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl group dead-letters discard orders billing 0:15 --yes

Read a counter’s sum, or add a signed delta to it. Counters live in a cache, beside its keys.

felixctl counter [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl counter add stats page-views 1
felixctl counter get stats page-views

Print a counter’s sum. Exits with status 5 when it has never been written.

felixctl counter get [OPTIONS] <CACHE> <KEY>
Argument Required Description
CACHE yes Cache the counter lives in
KEY yes Counter key

Examples:

Terminal window
felixctl counter get stats page-views
felixctl counter get stats page-views --json

Add DELTA, which may be negative, to a counter and print its sum including the add. A counter that has never been written starts at zero. The add is sent once: a failure is not retried, since the broker may already have applied it.

felixctl counter add [OPTIONS] <CACHE> <KEY> <DELTA>
Argument Required Description
CACHE yes Cache the counter lives in
KEY yes Counter key
DELTA yes Signed amount to add

Examples:

Terminal window
felixctl counter add stats page-views 1
felixctl counter add stats stock -3

Create, list, inspect and delete tenants. Needs a control-plane token allowed tenant.manage on the cluster.

felixctl tenant [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl tenant ls
felixctl tenant info t1
felixctl tenant create acme --display-name 'Acme Corp'
felixctl tenant rm acme --yes

List every tenant.

felixctl tenant ls [OPTIONS]

Examples:

Terminal window
felixctl tenant ls
felixctl tenant ls --json

Show one tenant. Exits with status 5 when it does not exist.

felixctl tenant info [OPTIONS] <TENANT>
Argument Required Description
TENANT yes Tenant id

Examples:

Terminal window
felixctl tenant info t1

Create a tenant. One that already exists is refused.

felixctl tenant create [OPTIONS] <TENANT>
Argument Required Description
TENANT yes Tenant id
Option Value Default Description
--display-name <TEXT> - Display name [default: the tenant id]

Examples:

Terminal window
felixctl tenant create acme
felixctl tenant create acme --display-name 'Acme Corp'

Delete a tenant with everything in it: namespaces, streams, caches, signing keys and RBAC rules. Asks first on a terminal; elsewhere it needs –yes.

felixctl tenant rm [OPTIONS] <TENANT>
Argument Required Description
TENANT yes Tenant id
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl tenant rm acme
felixctl tenant rm acme --yes

Create, list, inspect and delete the namespaces of the current tenant.

felixctl namespace [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl namespace ls
felixctl namespace info default --tenant t1
felixctl namespace create payments
felixctl namespace rm payments --yes

List the namespaces of the current tenant.

felixctl namespace ls [OPTIONS]

Examples:

Terminal window
felixctl namespace ls
felixctl namespace ls --tenant acme

Show one namespace of the current tenant.

felixctl namespace info [OPTIONS] <NAMESPACE>
Argument Required Description
NAMESPACE yes Namespace name

Examples:

Terminal window
felixctl namespace info default

Create a namespace in the current tenant. One that already exists is refused.

felixctl namespace create [OPTIONS] <NAMESPACE>
Argument Required Description
NAMESPACE yes Namespace name
Option Value Default Description
--display-name <TEXT> - Display name [default: the namespace name]

Examples:

Terminal window
felixctl namespace create payments
felixctl namespace create payments --display-name Payments

Delete a namespace of the current tenant, its streams and caches included. Asks first on a terminal; elsewhere it needs –yes.

felixctl namespace rm [OPTIONS] <NAMESPACE>
Argument Required Description
NAMESPACE yes Namespace name
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl namespace rm payments
felixctl namespace rm payments --yes

Create, change, list, inspect and delete the streams of the current tenant and namespace.

felixctl stream [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl stream ls
felixctl stream info orders
felixctl stream create orders --shards 4 --replication 3 --consistency quorum
felixctl stream set orders --retention-secs 86400
felixctl stream rm orders --yes

List the streams of the current tenant and namespace.

felixctl stream ls [OPTIONS]

Examples:

Terminal window
felixctl stream ls
felixctl stream ls -n payments --json

Show a stream’s shards, replication, retention, consistency and delivery settings.

felixctl stream info [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream name

Examples:

Terminal window
felixctl stream info orders
felixctl stream info orders --json

Create a stream in the current tenant and namespace. Creating one that already exists with the same settings succeeds; with different settings it is refused. Shards, replication, region and routing are fixed once it exists.

felixctl stream create [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream name
Option Value Default Description
--shards <N> 1 Shards; fixed at creation
--replication <N> 1 Brokers holding a copy of each shard, the leader included. quorum needs at least 3 to mean anything
--kind <KIND> stream The kind the control plane records for the stream. One of stream, queue.
--consistency <LEVEL> leader quorum acknowledges a publish once a majority of the shard’s copies hold it. One of leader, quorum.
--delivery <GUARANTEE> at-least-once The delivery guarantee readers get. One of at-most-once, at-least-once.
--durable <BOOL> true Keep records in an on-disk log. false keeps them in memory only. One of true, false.
--retention-secs <SECS> - Keep records this many seconds [default: the broker’s own bound]
--retention-bytes <BYTES> - Keep at most this many bytes per shard [default: the broker’s own bound]
--region <REGION> - Region the stream’s data must stay in; fixed at creation [default: anywhere]
--routing <ROUTING> modulo How routing keys map to shards; fixed at creation. jump-hash needs the jump_hash_routing fleet feature finalized. One of modulo, jump-hash.

Examples:

Terminal window
felixctl stream create orders
felixctl stream create orders --shards 4 --replication 3 --consistency quorum
felixctl stream create audit --retention-secs 604800 --region eu-west

Change a stream’s consistency, delivery, durability or retention, and print what changed. A retention bound not given keeps its current value.

felixctl stream set [OPTIONS] <--consistency <LEVEL>|--delivery <GUARANTEE>|--durable <BOOL>|--retention-secs <SECS>|--retention-bytes <BYTES>> <STREAM>
Argument Required Description
STREAM yes Stream name
Option Value Default Description
--consistency <LEVEL> - New consistency level. One of leader, quorum.
--delivery <GUARANTEE> - New delivery guarantee. One of at-most-once, at-least-once.
--durable <BOOL> - Keep records in an on-disk log, or not. One of true, false.
--retention-secs <SECS> - Keep records this many seconds; default for the broker’s own bound
--retention-bytes <BYTES> - Keep at most this many bytes per shard; default for the broker’s own bound

Examples:

Terminal window
felixctl stream set orders --retention-secs 86400
felixctl stream set orders --retention-bytes default
felixctl stream set orders --consistency quorum

Hide the records of one shard of a durable stream below an offset, only if the shard’s next offset is exactly –expected-offset. The trim is a record of its own and lands at that offset, so –before can be at most that. Reads below the new floor are refused as too old.

A stale –expected-offset is refused with the shard’s next offset and exit status 4, and nothing is written. A trim that times out may still have been written and exits with status 6; the same command again is then refused with the tail, so read the shard’s earliest offset to tell. Needs a token allowed stream.trim, and a broker fleet that has finalized head trims.

felixctl stream trim [OPTIONS] --shard <N> --before <OFFSET> --expected-offset <OFFSET> <STREAM>
Argument Required Description
STREAM yes Stream name
Option Value Default Description
--shard <N> - The shard to trim
--before <OFFSET> - The new floor: records below this offset are hidden
--expected-offset <OFFSET> - The shard’s next offset, as the caller last saw it
--headers <TEXT> - Kept with the trim and shown to a reader refused below its floor

Examples:

Terminal window
felixctl stream trim orders --shard 0 --before 1000 --expected-offset 5000
felixctl stream trim orders --shard 2 --before 400 --expected-offset 410 --headers holder-7

Delete a stream and its records. Asks first on a terminal; elsewhere it needs –yes.

felixctl stream rm [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream name
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl stream rm orders
felixctl stream rm orders --yes

List and inspect the brokers registered with the control plane, with their lifecycle and whether placement may use them, and drain or deregister one.

felixctl node [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl node ls
felixctl node info broker-1 --json
felixctl node drain broker-2
felixctl node deregister broker-2 --yes

List the brokers registered with the control plane.

felixctl node ls [OPTIONS]

Examples:

Terminal window
felixctl node ls
felixctl node ls --json

Show one broker: its addresses, lifecycle, heartbeat and placement eligibility.

felixctl node info [OPTIONS] <NODE>
Argument Required Description
NODE yes Node id

Examples:

Terminal window
felixctl node info broker-1

Mark a broker draining: placement puts nothing new on it and moves the shards it holds to other brokers, while it keeps serving each one until the shard is handed off. Draining a node already draining succeeds. Asks first on a terminal; elsewhere it needs –yes.

felixctl node drain [OPTIONS] <NODE>
Argument Required Description
NODE yes Node id
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl node drain broker-2
felixctl node drain broker-2 --yes

Mark a broker as having left the cluster on purpose. Its shards stay put until its lease has run out, then fail over. Drain it first to move them without a failover. Asks first on a terminal; elsewhere it needs –yes.

felixctl node deregister [OPTIONS] <NODE>
Argument Required Description
NODE yes Node id
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl node deregister broker-2
felixctl node deregister broker-2 --yes

List which broker leads each shard of every stream and cache, as the control plane assigned them, list the moves in progress, and move a shard’s leadership or cancel a move.

felixctl shard [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl shard ls
felixctl shard ls --leader broker-2
felixctl shard moves
felixctl shard move orders 2 --to broker-3
felixctl shard move cancel orders 2

List shard assignments: for each shard of each stream and cache, its leader, replicas, generation and state.

felixctl shard ls [OPTIONS]
Option Value Default Description
--leader <NODE> - Only shards this node leads
--name <NAME> - Only shards of this stream or cache

Examples:

Terminal window
felixctl shard ls
felixctl shard ls --leader broker-2
felixctl shard ls --name orders --json

Move a shard’s leadership to the broker –to names. The destination copies the log first and the leader keeps serving until it has caught up. Prints the step the move is at and the assignment it wrote. –dry-run prints what it would write without starting it.

shard move cancel stops a move that has not cut over yet.

felixctl shard move [OPTIONS] --to <NODE> <NAME> <SHARD>
felixctl shard move <COMMAND>
Argument Required Description
NAME yes Stream (or, with –cache, cache) name
SHARD yes Shard number
Option Value Default Description
--to <NODE> - Broker to move the leadership to
--cache - - NAME is a cache, not a stream
--dry-run - - Print what the move would write, without starting it

Examples:

Terminal window
felixctl shard move orders 2 --to broker-3
felixctl shard move orders 2 --to broker-3 --dry-run
felixctl shard move sessions 0 --to broker-1 --cache
felixctl shard move cancel orders 2

Cancel a shard’s move or follower replacement, whoever started it. Before the fence the destination is dropped; after it the old leader serves again. A move that has cut over cannot be cancelled; move the shard back instead. Placement may choose the same move again, so pause it first to keep the shard where it is.

felixctl shard move cancel [OPTIONS] <NAME> <SHARD>
Argument Required Description
NAME yes Stream (or, with –cache, cache) name
SHARD yes Shard number
Option Value Default Description
--cache - - NAME is a cache, not a stream

Examples:

Terminal window
felixctl shard move cancel orders 2
felixctl shard move cancel sessions 0 --cache

List the shard moves in progress: the step each is at, why it started, the old and new leader and how far the destination’s copy lags. Says so when placement is paused.

felixctl shard moves [OPTIONS]

Examples:

Terminal window
felixctl shard moves
felixctl shard moves --json

See what placement would do next and which shards are short of their replication factor, pause or resume the moves placement starts by itself, and give up a stranded shard’s log. Reading needs a control-plane token allowed node.view on the cluster; pausing, resuming and abandoning need node.manage.

felixctl placement [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl placement plan
felixctl placement replication
felixctl placement pause
felixctl placement resume
felixctl placement abandon orders 2 --yes

Show what placement would do next for each shard it has work for: stage a move, wait for a slot, or leave it. Starts nothing.

felixctl placement plan [OPTIONS]

Examples:

Terminal window
felixctl placement plan

Show the shards with fewer copies than their replication factor: how many they have, which copies are on brokers that are unavailable, which are halted and why, and the broker a copy is being added on.

felixctl placement replication [OPTIONS]

Examples:

Terminal window
felixctl placement replication

Stop placement starting moves of its own, on every control-plane instance. Moves already under way finish; cancel one to stop it. New shards are still placed and a failed leader is still replaced, and an operator can still move shards.

felixctl placement pause [OPTIONS]

Examples:

Terminal window
felixctl placement pause

Let placement start moves of its own again.

felixctl placement resume [OPTIONS]

Examples:

Terminal window
felixctl placement resume

Give up the log of a durable shard that placement is holding unplaced because the only copies of it are out of reach, and place the shard afresh. Records only the old leader held are lost, acknowledged ones included. The control plane refuses it while the leader serves or a replica can take over without loss. Never asks: it always needs –yes.

felixctl placement abandon [OPTIONS] <NAME> <SHARD>
Argument Required Description
NAME yes Stream (or, with –cache, cache) name
SHARD yes Shard number
Option Value Default Description
--cache - - NAME is a cache, not a stream
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl placement abandon orders 2 --yes
felixctl placement abandon sessions 0 --cache --yes

A fleet feature is a behaviour every serving broker must support before it is switched on. features ls shows which each broker version offers and which are on; features finalize switches one on fleet-wide. Finalizing is one-way: brokers without the feature are refused afterwards. Reading needs a control-plane token allowed node.view on the cluster; finalizing needs node.manage.

felixctl features [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl features ls
felixctl features finalize jump_hash_routing --dry-run
felixctl features finalize jump_hash_routing --yes

Show how many brokers are serving, the features every one of them supports, and the features finalized fleet-wide.

felixctl features ls [OPTIONS]

Examples:

Terminal window
felixctl features ls
felixctl features ls --json

Switch a feature on for the whole fleet. ONE-WAY: it cannot be turned off, and brokers without the feature are refused from then on. The control plane refuses it unless every serving broker supports the feature and the features it needs are on. –dry-run says whether it would be accepted and changes nothing.

felixctl features finalize [OPTIONS] <FEATURE>
Argument Required Description
FEATURE yes Feature name, as features ls lists it
Option Value Default Description
--dry-run - - Say whether it could be finalized, without finalizing it
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl features finalize jump_hash_routing --dry-run
felixctl features finalize jump_hash_routing --yes

Record one committed offset per shard log, across every broker, and write them to a manifest a restore cuts back to. The offsets are read from each shard leader’s metrics listener, so run it from somewhere that can reach those listeners. Reading needs a control-plane token allowed node.view on the cluster.

The brokers do not agree on an instant, so a record written while the point is collected can be in it on one shard and not on another.

felixctl backup-point [OPTIONS] <NAME>
Argument Required Description
NAME yes Name recorded in the manifest
Option Value Default Description
--out <FILE> - Where to write the manifest [default: NAME.backup-point.json]
--broker <NODE=URL> - Metrics URL of a broker, where the address the control plane has for it is not the one to use. Repeat for more brokers
--metrics-port <PORT> 8080 Port of the brokers’ metrics listeners

Examples:

Terminal window
felixctl backup-point nightly-2026-11-05
felixctl backup-point nightly --out /backups/nightly.json
felixctl backup-point nightly --broker broker-1=http://10.0.0.5:9090 --metrics-port 9090

List, add and remove the current tenant’s RBAC rules.

A policy lets a subject (usually a role) take an action on an object. A grouping assigns a user, or an IdP group, to a role. Changes reach brokers with the next token the principal is issued.

felixctl rbac [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl rbac policy ls
felixctl rbac policy add role:reader stream:t1/payments/orders stream.subscribe
felixctl rbac grouping add p:alice role:reader
felixctl rbac policy rm role:reader stream:t1/payments/orders stream.subscribe --yes

List, add and remove policies. Each one is a subject, an object and an action.

Objects: cluster:*, node:{node}, tenant:{tenant}, namespace:{tenant}/{ns}, stream:{tenant}/{ns}/{stream}, cache:{tenant}/{ns}/{cache}, cache:{tenant}/{ns}/{cache}/{key}, cache:{tenant}/{ns}/{cache}/{prefix}*, and group:{tenant}/{ns}/{stream}/{group}. A * may stand for a stream, cache or group, and for the namespace above it when it does.

felixctl rbac policy [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl rbac policy ls --subject role:reader
felixctl rbac policy add role:reader stream:t1/payments/* stream.subscribe
felixctl rbac policy add role:session-1 cache:t1/default/sessions/user-1 cache.read
felixctl rbac policy add role:users cache:t1/default/sessions/user:* cache.write
felixctl rbac policy rm role:reader stream:t1/payments/* stream.subscribe

List the tenant’s policies that the control-plane token may see.

felixctl rbac policy ls [OPTIONS]
Option Value Default Description
--subject <SUBJECT> - Only policies for this subject

Examples:

Terminal window
felixctl rbac policy ls
felixctl rbac policy ls --subject role:reader --json

Let SUBJECT take ACTION on OBJECT. The object is checked here before it is sent; the control plane checks it again, along with the action and whether the token may grant it. A cache key or key prefix object takes only cache.read or cache.write.

felixctl rbac policy add [OPTIONS] <SUBJECT> <OBJECT> <ACTION>
Argument Required Description
SUBJECT yes Who the policy is for, usually a role such as role:reader
OBJECT yes What it covers, such as stream:t1/payments/orders
ACTION yes What it allows, such as stream.publish

Examples:

Terminal window
felixctl rbac policy add role:writer stream:t1/payments/orders stream.publish
felixctl rbac policy add role:users cache:t1/default/sessions/user:* cache.read

Remove one policy, named exactly as policy ls prints it. Asks first on a terminal; elsewhere it needs –yes. Exits with status 5 when there is no such policy.

felixctl rbac policy rm [OPTIONS] <SUBJECT> <OBJECT> <ACTION>
Argument Required Description
SUBJECT yes Who the policy is for, usually a role such as role:reader
OBJECT yes What it covers, such as stream:t1/payments/orders
ACTION yes What it allows, such as stream.publish
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl rbac policy rm role:writer stream:t1/payments/orders stream.publish
felixctl rbac policy rm role:writer stream:t1/payments/orders stream.publish --yes

List, add and remove groupings. Each one assigns a user, or a group named by an IdP claim, to a role.

felixctl rbac grouping [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl rbac grouping ls --role role:reader
felixctl rbac grouping add p:alice role:reader
felixctl rbac grouping rm p:alice role:reader

List the tenant’s groupings for roles the control-plane token may see.

felixctl rbac grouping ls [OPTIONS]
Option Value Default Description
--user <USER> - Only groupings for this user or group
--role <ROLE> - Only groupings to this role

Examples:

Terminal window
felixctl rbac grouping ls
felixctl rbac grouping ls --user p:alice --json

Assign ROLE to USER. The token must be able to grant every policy the role carries.

felixctl rbac grouping add [OPTIONS] <USER> <ROLE>
Argument Required Description
USER yes The user or group, such as p:alice
ROLE yes The role, such as role:reader

Examples:

Terminal window
felixctl rbac grouping add p:alice role:reader

Take ROLE away from USER. Asks first on a terminal; elsewhere it needs –yes. Exits with status 5 when there is no such assignment.

felixctl rbac grouping rm [OPTIONS] <USER> <ROLE>
Argument Required Description
USER yes The user or group, such as p:alice
ROLE yes The role, such as role:reader
Option Value Default Description
-y, --yes - - Do not ask for confirmation. Needed when stdin is not a terminal

Examples:

Terminal window
felixctl rbac grouping rm p:alice role:reader --yes

Look at what the brokers themselves hold, read-only. Each answer is one broker’s own view; felixctl asks every broker that has a part in what is shown.

Needs a broker token allowed node.view on cluster:*. A broker too old to answer is reported, not guessed at.

felixctl inspect [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl inspect shard orders --shard 3
felixctl inspect shard acme/default/orders
felixctl inspect shard sessions --cache --json
felixctl inspect subs orders --dropping
felixctl inspect subs --node broker-a --limit 500

Show one shard as its brokers see it: the generation and leader, whether the leader serves and why not, the fence a promoted leader waits on, its lease, the tail and commit mark, and each replica’s position and state.

The assignment comes from the control plane when a control-plane URL is configured, else from the broker connected to. Every broker in it is then asked directly; one that cannot be reached is listed under unreachable rather than described. Without –shard, every shard of the stream is shown.

felixctl inspect shard [OPTIONS] <NAME>
Argument Required Description
NAME yes Stream (or, with –cache, cache) name, or TENANT/NAMESPACE/NAME for another tenant’s
Option Value Default Description
--shard <N> - Only this shard
--cache - - NAME is a cache, not a stream

Examples:

Terminal window
felixctl inspect shard orders --shard 3
felixctl inspect shard acme/default/orders
felixctl inspect shard sessions --cache --shard 0 --json

List the subscriptions each broker serves: the stream and shard, the connection and principal it delivers to, the queue’s overflow policy, depth and capacity, the records it has dropped, and its position against the shard’s tail.

Every broker the cluster advertises is asked, or only –node. A page holds –limit subscriptions per broker (at most 1000); when a broker has more, felixctl prints the –cursor that continues from there. Depth and capacity count batches; dropped counts records.

felixctl inspect subs [OPTIONS] [STREAM]
Argument Required Description
STREAM no Only this stream: NAME, or TENANT/NAMESPACE/NAME for another tenant’s
Option Value Default Description
--shard <N> - Only this shard of the stream
--node <NODE> - Only this broker, by node id
--principal <P> - Only subscriptions made under this principal
--dropping - - Only subscriptions that have dropped records
--limit <N> 100 At most this many per broker (1-1000)
--cursor <C> - Continue after the page a previous run printed

Examples:

Terminal window
felixctl inspect subs
felixctl inspect subs orders --shard 0
felixctl inspect subs --dropping --json
felixctl inspect subs --principal p:billing
felixctl inspect subs --node broker-a --cursor eyJ0ZW5hbnRfaWQiOi4uLn0

Work on a broker’s data directory with the tools in the felix-broker binary. These run on the host that holds the directory, with felix-broker installed there: felixctl finds it with –broker-bin (before data), then $FELIX_BROKER_BIN, then PATH, passes every argument after the subcommand through unchanged, –help included, and ends with its exit status.

data inspect segments\|records reads a data directory, read-only: what startup would decide about every shard’s segments, and the records around an offset. data restore-point cuts a stopped broker’s logs back to a backup point written by felixctl backup-point. For their own usage run felixctl data inspect --help or felixctl data restore-point --help.

felixctl data [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl data inspect segments /var/lib/felix/data
felixctl data inspect records /var/lib/felix/data acme/default/orders/3 --offset 1500
felixctl data restore-point --point nightly.backup-point.json --node broker-1

Run the maintenance tools in the felix-controlplane binary. They read or write the control plane’s own database, so they run on a host that can reach it, with felix-controlplane installed there: felixctl finds it with –controlplane-bin (before controlplane), then $FELIX_CONTROLPLANE_BIN, then PATH, passes every argument after migrate through unchanged, –help included, and ends with its exit status. migrate export-postgres writes the metadata to a file; migrate import loads a file into a Raft group.

felixctl controlplane [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl controlplane migrate export-postgres state.json
felixctl controlplane migrate import state.json http://cp-0:8444

Run one of felix-loadgen’s scenarios against the current context and print a short summary: the rate, and p50 and p99 latency.

The defaults are small enough to finish in seconds. The stream or cache must already exist. –json prints the summary together with the full felix-loadgen result.

felixctl bench [OPTIONS] <COMMAND>

Examples:

Terminal window
felixctl bench latency orders
felixctl bench fanout orders --fanout 20
felixctl bench ingest orders --concurrency 8 --duration-secs 30
felixctl bench cache sessions --json

Measure aggregate publish throughput: –concurrency publishers, each on its own connection, send batches with –in-flight acknowledged batches outstanding. No subscribers. Reports msg/s, MB/s and batch acknowledgement latency.

felixctl bench ingest [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream to publish to
Option Value Default Description
--total <N> 100000 Records to publish in total
--payload-bytes <BYTES> 256 Payload size in bytes
--concurrency <N> 4 Publishers, each on its own connection
--batch <N> 64 Records per batch
--in-flight <N> 4 Acknowledged batches each publisher keeps outstanding; 0 sends without acknowledgements
--keys <N> 0 Spread batches over this many routing keys; 0 publishes unkeyed, which puts everything on shard 0
--duration-secs <SECS> - Publish for this many seconds instead of –total records

Examples:

Terminal window
felixctl bench ingest orders
felixctl bench ingest orders --concurrency 8 --batch 256 --duration-secs 30
felixctl bench ingest orders --keys 64 --in-flight 0

Measure latency with one publisher and one subscriber: the publish acknowledgement round trip and the publish-to-delivery time.

felixctl bench latency [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream to publish to and subscribe to
Option Value Default Description
--total <N> 5000 Operations measured
--warmup <N> 500 Operations run first and not measured
--payload-bytes <BYTES> 256 Payload size in bytes

Examples:

Terminal window
felixctl bench latency orders
felixctl bench latency orders --total 20000 --payload-bytes 1024

Measure fanout: one publisher and –fanout subscribers. Reports the publish rate, the delivered rate across all subscribers, and delivery latency.

felixctl bench fanout [OPTIONS] <STREAM>
Argument Required Description
STREAM yes Stream to publish to and subscribe to
Option Value Default Description
--fanout <N> 10 Subscribers
--total <N> 5000 Operations measured
--warmup <N> 500 Operations run first and not measured
--payload-bytes <BYTES> 256 Payload size in bytes

Examples:

Terminal window
felixctl bench fanout orders
felixctl bench fanout orders --fanout 50

Measure cache round trips: puts, then gets of the same keys, from –concurrency workers spread across the brokers.

felixctl bench cache [OPTIONS] <CACHE>
Argument Required Description
CACHE yes Cache to write and read
Option Value Default Description
--concurrency <N> 8 Concurrent workers
--total <N> 5000 Operations measured
--warmup <N> 500 Operations run first and not measured
--payload-bytes <BYTES> 256 Payload size in bytes

Examples:

Terminal window
felixctl bench cache sessions
felixctl bench cache sessions --concurrency 32 --payload-bytes 64

Print a completion script for SHELL to stdout. Source it from your shell’s startup file.

felixctl completions [OPTIONS] <SHELL>
Argument Required Description
SHELL yes Shell to generate the script for. One of bash, elvish, fish, powershell, zsh.

Examples:

Terminal window
felixctl completions bash > ~/.local/share/bash-completion/completions/felixctl
felixctl completions zsh > "${fpath[1]}/_felixctl"
felixctl completions fish > ~/.config/fish/completions/felixctl.fish