Skip to content

CLI

Karafka has a simple CLI built in. It provides the following commands:

Command Description
help Describe available commands
console Start the Karafka irb console similar to the Rails console (short-cut alias: "c")
info Print configuration details and other options of your application
install Installs all required things for Karafka application in current directory
server Start the Karafka server (short-cut aliases: "s", "consumer")
swarm Start the Karafka server in the swarm mode (multiple forked processes)
topics Allows for topics management (create, delete, repartition, reset, migrate, align, plan)
topics health Check Kafka topics for replication and durability issues (Pro)

All the commands are executed the same way:

bundle exec karafka [COMMAND]

To list all available commands with a short description of each, run:

bundle exec karafka help

Karafka server

Limiting consumer groups used per process

Karafka supports having multiple consumer groups within a single application. You can run multiple Karafka instances, specifying consumer groups that should be running per each process using the --include-consumer-groups server flag as follows:

bundle exec karafka server --include-consumer-groups group_name1,group_name3

If you specify none, by default, all will run.

You can also exclude certain consumer groups by using the --exclude-consumer-groups flag:

bundle exec karafka server --exclude-consumer-groups group_name2,group_name3

Limiting subscription groups used per process

Karafka supports having multiple subscription groups within a single application. You can run multiple Karafka instances, specifying subscription groups that should be running per each process using the --include-subscription-groups server flag as follows:

bundle exec karafka server --include-subscription-groups group_name1,group_name3

If you specify none, by default, all will run.

You can also exclude certain subscription groups by using the --exclude-subscription-groups flag:

bundle exec karafka server --exclude-subscription-groups group_name2,group_name3

Handling Multiplexed Subscription Groups in CLI Commands

Multiplexed subscription group replicas share the same name; multiplexing does not add any postfix to it. Use the subscription group's own name, the same one you would use without multiplexing, when including or excluding it via CLI flags.

Limiting topics used per process

Karafka supports having multiple topics within a single application. You can run multiple Karafka instances, specifying topics that should be running per each process using the --include-topics server flag as follows:

bundle exec karafka server --include-topics topic_name1,topic_name3

If you specify none, by default, all will run.

You can also exclude certain topics by using the --exclude-topics flag:

bundle exec karafka server --exclude-topics topic_name2,topic_name5

Karafka Topics Health

topics health Is a Pro Command

The topics health command is part of Karafka Pro.

The topics health command analyzes your Kafka topics for replication and durability issues. It inspects each topic's replication factor and min.insync.replicas setting to detect potential risks.

bundle exec karafka topics health

The command checks for the following conditions:

  • No Redundancy - Topics with a replication factor of 1, meaning no replicas exist. Any single broker failure will cause data loss.
  • Zero Fault Tolerance - Topics where the replication factor is less than or equal to min.insync.replicas, meaning no broker can fail without causing the topic to become unavailable for writes when producers use acks=all.
  • Low Durability - Topics where min.insync.replicas is set to 1, meaning acknowledged writes using acks=all only require a single broker, increasing the risk of data loss if that broker fails before replication completes.

Each finding is printed as it is found (in cluster order, not grouped by severity), shown in red for critical issues or yellow for warnings. After all topics are checked, if any issues were found, a generic recommendations summary is printed, covering increasing the replication factor, raising min.insync.replicas, and keeping the replication factor above min.insync.replicas for fault tolerance. If no issues were found, a single "All topics are healthy" confirmation is printed instead.

Karafka Swarm

Swarm has its own section. You can read about it here.

Declarative Topics

Declarative Topics managament via the CLI has its own section. You can read about that here.

Routing Patterns

Routing Patterns managament via the CLI has its own section. You can read about that here.

See Also

Last modified: 2026-08-15 23:02:38