Documentation

Command-Line Tool

Overview

Offset Explorer includes a command-line interface for Kafka administration, message operations, Consumers, Schema Registry, Kafka Connect, and saved JSON tool projects. Commands use the same saved connections as the desktop application.

Tool Location

On Windows and Linux, the command-line tool is installed in the same directory as the Offset Explorer GUI application. On macOS, it is located inside the application bundle:

/Applications/Offset Explorer 4.app/Contents/Resources/app

Use the executable for your platform followed by one command and its arguments:

commandline.exe -listTopics -serverConnection docker
./commandline -listTopics -serverConnection docker

Use commandline.exe on Windows. Use ./commandline on Linux and macOS. The examples below use Windows syntax; replace commandline.exe with ./commandline on Linux and macOS.

General

Command and option names are case-sensitive. Values may be case-sensitive depending on the operation.
Quote values and file paths containing spaces.
Program output is written to stdout. Application logging is written to commandline.log.
Errors are written to standard error.
Commands that produce output support -outputFormat text|json|xml|csv. The default is text. This does not apply to viewMessages or help output.
A successful command exits with status 0. A failed command exits with a nonzero status.
Commands that use Kafka, Schema Registry, or Kafka Connect require a matching saved connection unless the command creates that connection.
Destructive commands do not display a confirmation prompt.

Command Output Formats

For non-text output, each result is written as one record per line so long-running commands can stream results as they are produced. CSV records use name=value pairs, for example:

topic=orders,partition=0,messageCount=125

Help

commandline.exe -help

commandline.exe -h addTopic

commandline.exe -h all

-help or -h without a value lists commands. Supply a command name for detailed help, or all for all command help.

Credentials, tokens, passwords, and JAAS configuration passed on the command line may be visible in shell history and operating-system process listings.

Message Output Formats

viewMessages and findMessages commands accept independent -keyFormat and -valueFormat arguments:

Value	Output
`hex`	Uppercase hexadecimal byte pairs separated by spaces.
`hexNoSpaces`	Uppercase hexadecimal with no spaces.
`text`	UTF-8 text with original line breaks.
`textNoNewlines`	UTF-8 text with carriage returns and line feeds removed.

Saved JSON Files

exportMessages, importMessages, generateData, and findMessages use JSON project files saved by the corresponding Offset Explorer UI tool. The file contains the connection, Topic, and complete tool settings.

Commands

Help Command

help

Lists commands or displays detailed help for one or all commands.

-help
-h [<command>|all]

commandline.exe -help

commandline.exe -h addTopic

commandline.exe -h all

Server Commands

addServerConnection

Adds and saves a Kafka server connection.

-addServerConnection -name <name> -bootstrapServers <servers> [options]

Argument	Description
`-name`	Saved connection name.
`-bootstrapServers`	Comma-separated `host:port` Broker endpoints.
`-version`	Kafka version. Default: latest supported version.
`-zookeeperHost`	ZooKeeper host. Default: `localhost`.
`-zookeeperPort`	ZooKeeper port. Default: `2181`.
`-chroot`	ZooKeeper chroot. Default: `/`.
`-security`	`plaintext`, `ssl`, `sasl_plaintext`, or `sasl_ssl`. Default: `plaintext`.
`-saslMechanism`	SASL mechanism such as `PLAIN`, `SCRAM-SHA-512`, or `OAUTHBEARER`.
`-saslCallbackHandlerClass`	SASL callback handler class name.
`-saslEndpointToken`	OAuth/OIDC token endpoint URL.
`-jaasConfig`	Inline JAAS configuration. Quote the whole value because it contains spaces.
`-truststoreLocation`, `-truststorePassword`	SSL truststore path and password.
`-keystoreLocation`, `-keystorePassword`, `-keystorePrivateKey`	SSL keystore path, store password, and private-key password.
`-validateSslEndpointHostname`	`true` or `false`. Default: `false`.
`-testConnection`	Test before saving. Default: `true`.

For SASL/PLAIN, include -saslMechanism PLAIN. In Windows cmd.exe, wrap the JAAS config in double quotes and escape the quotes inside the config as \".

commandline.exe -addServerConnection -name cloud -bootstrapServers pkc-example:9092 -security sasl_ssl -saslMechanism PLAIN -jaasConfig "org.apache.kafka.common.security.plain.PlainLoginModule required username=\"API_KEY\" password=\"API_SECRET\";"

In PowerShell, single quotes around the whole JAAS config are usually simpler because the inner double quotes do not need escaping.

.\commandline.exe -addServerConnection -name cloud -bootstrapServers pkc-example:9092 -security sasl_ssl -saslMechanism PLAIN -jaasConfig 'org.apache.kafka.common.security.plain.PlainLoginModule required username="API_KEY" password="API_SECRET";'

commandline.exe -addServerConnection -name secure-cluster -bootstrapServers "broker1:9093,broker2:9093" -version 4.3 -security sasl_ssl -saslMechanism OAUTHBEARER -saslCallbackHandlerClass com.example.Callback -saslEndpointToken https://idp.example/token -jaasConfig "module required;" -truststoreLocation C:\certs\trust.jks -truststorePassword changeit -keystoreLocation C:\certs\client.p12 -keystorePassword changeit -keystorePrivateKey changeit -validateSslEndpointHostname true -testConnection true

deleteServerConnection

Deletes a saved server connection.

-deleteServerConnection <connection name>

commandline.exe -deleteServerConnection secure-cluster

listServerConnections

Lists saved connections and their version, security, hosts, and chroot settings.

-listServerConnections

commandline.exe -listServerConnections

testServerConnection

Validates that a saved Kafka server connection is reachable and can be connected to.

-testServerConnection <connection name>

commandline.exe -testServerConnection docker

Topic Commands

addTopic

Creates a Topic.

-addTopic <Topic> -serverConnection <name> [-partitionCount <count>] [-replicaCount <count>] [-configs <name=value,...>]

`-addTopic`	Topic name.
`-serverConnection`	Saved connection name.
`-partitionCount`	Partition count. Default: `1`.
`-replicaCount`	Replication factor. Default: `1`.
`-configs`	Comma-separated Topic configurations.

commandline.exe -addTopic orders -serverConnection docker -partitionCount 6 -replicaCount 3 -configs "cleanup.policy=compact,min.insync.replicas=2"

deleteTopic

Deletes a Topic.

-deleteTopic <Topic> -serverConnection <name>

commandline.exe -deleteTopic orders -serverConnection docker

listTopics

Lists Topics.

-listTopics -serverConnection <name>

commandline.exe -listTopics -serverConnection docker

describeTopic

Displays Partition count, replication factor, and Topic configurations.

-describeTopic <Topic> -serverConnection <name>

commandline.exe -describeTopic orders -serverConnection docker

messageCount

Counts messages for a Topic or selected Partitions.

-messageCount -topic <Topic> -serverConnection <name> [-partition <number|list|range>]

commandline.exe -messageCount -topic orders -serverConnection docker -partition 0-2

commandline.exe -messageCount -topic orders -serverConnection docker -partition "[0,2,4]"

Message Commands

addMessage

Adds one Kafka message. At least one of -key or -value is required.

-addMessage -serverConnection <name> -topic <Topic> [-partition <number>] [-key <data>] [-value <data>] [-keyFormat string|hex] [-valueFormat string|hex] [-header <name=value,...>]

Partition defaults to 0. Key and value formats default to string.

commandline.exe -addMessage -serverConnection docker -topic orders -partition 2 -key 0123AB -keyFormat hex -value "{\"status\":\"created\"}" -valueFormat string -header "source=cli,type=order"

addMessages

Interactively adds multiple messages. Enter one message per line and enter exit to finish. Enter h to add Headers as name=value, then done to return to messages. The command output includes the Partition and Offset for each added message.

-addMessages -serverConnection <name> -topic <Topic> [-partition <number>] [-format k,v|v,k|k|v] [-keyFormat text|hex] [-valueFormat text|hex]

Partition defaults to 0. Format defaults to k,v. Key and value formats default to text. When hex is used, enter hexadecimal bytes.

commandline.exe -addMessages -serverConnection docker -topic orders -partition 1 -format k,v -keyFormat hex -valueFormat text
CAFE,created-value
CAFF,updated-value
exit

viewMessages

Displays messages from a Topic or selected Partitions. The default limit is 10,000 messages per Partition.

-viewMessages -topic <Topic> -serverConnection <name> [options]

`-partition`	One Partition (`1`), list (`[1,4,6]`), or range (`1-5`).
`-first`	Read the first number of messages.
`-last`	Read the last number of messages.
`-fromOffset`	Start at an Offset. Requires exactly one Partition.
`-keyFilter`, `-valueFilter`	Substring filters.
`-keyFilterRegex`, `-valueFilterRegex`	Regular-expression filters.
`-keyFormat`, `-valueFormat`	`hex`, `hexNoSpaces`, `text`, or `textNoNewlines`. Default: `text`.
`-format`	Output template. Tokens: `#topic#`, `#partition#`, `#offset#`, `#key#`, `#keyAsHex#`, `#value#`, and `#valueAsHex#`.

-first, -last, and -fromOffset are mutually exclusive.

commandline.exe -viewMessages -topic orders -serverConnection docker -partition "[1,2,3]" -first 100 -keyFilter "customer-" -valueFilterRegex "created|updated" -keyFormat textNoNewlines -valueFormat text -format "#partition#:#offset# key=#key# value=#value#"

commandline.exe -viewMessages -topic orders -serverConnection docker -partition 0 -fromOffset 500 -keyFilterRegex "order-[0-9]+" -valueFilter "created" -keyFormat hex -valueFormat hexNoSpaces

commandline.exe -viewMessages -topic orders -serverConnection docker -partition 0 -last 10

Tool Commands

exportMessages

Runs an Export Tool project saved as JSON. See Saving and Loading Export Projects.

-exportMessages <settings JSON file>

commandline.exe -exportMessages "C:\Offset Explorer Projects\export-orders.json"

importMessages

Runs an Import Tool project saved as JSON. See Importing Messages.

-importMessages <settings JSON file>

commandline.exe -importMessages "C:\Offset Explorer Projects\import-orders.json"

generateData

Runs a Data Generator project saved as JSON. See Saving and Loading Data Generator Projects.

-generateData <settings JSON file>

commandline.exe -generateData "C:\Offset Explorer Projects\generate-orders.json"

findMessages

Runs a Find Messages project saved as JSON. Search criteria come from the project file.

-findMessages <settings JSON file> [-keyFormat <format>] [-valueFormat <format>]

Both formats accept hex, hexNoSpaces, text, and textNoNewlines. Both default to hexNoSpaces.

commandline.exe -findMessages "C:\Offset Explorer Projects\find-orders.json" -keyFormat textNoNewlines -valueFormat hex

Consumer Commands

listConsumers

Lists Consumers and their active state.

-listConsumers -serverConnection <name>

commandline.exe -listConsumers -serverConnection docker

viewConsumerOffsets

Displays committed Offset and lag information.

-viewConsumerOffsets -serverConnection <name> -consumer <Consumer> [-topic <Topic>] [-format <template>]

Format tokens are #topic#, #partition#, #start#, #end#, #offset#, and #lag#.

commandline.exe -viewConsumerOffsets -serverConnection docker -consumer billing -topic orders -format "#topic#:#partition# offset=#offset# lag=#lag#"

updateConsumerOffset

Updates a committed Consumer Offset, assigns a Partition, or creates a Consumer.

-updateConsumerOffset -serverConnection <name> -topic <Topic> -partition <number> -consumer <Consumer> -offset <Offset> [-newConsumer true|false]

-newConsumer defaults to false.

commandline.exe -updateConsumerOffset -serverConnection docker -topic orders -partition 0 -consumer billing -offset 500 -newConsumer true

deleteConsumer

Deletes a Consumer group.

-deleteConsumer <Consumer> -serverConnection <name>

commandline.exe -deleteConsumer billing -serverConnection docker

Schema Registry Commands

addSchemaRegistry

Adds a saved Schema Registry connection.

-addSchemaRegistry <name> -endpoint <URL> [-key <key>] [-secret <secret>] [-truststoreLocation <file>] [-truststorePassword <password>] [-keystoreLocation <file>] [-keystorePassword <password>] [-keystorePrivateKey <password>]

commandline.exe -addSchemaRegistry production-registry -endpoint https://registry.example.com -key api-key -secret api-secret -truststoreLocation C:\certs\trust.jks -truststorePassword changeit -keystoreLocation C:\certs\client.p12 -keystorePassword changeit -keystorePrivateKey changeit

listSchemaRegistries

Lists saved Schema Registry connections.

-listSchemaRegistries

commandline.exe -listSchemaRegistries

describeSchemaRegistry

Displays endpoint, mode, and compatibility configuration.

-describeSchemaRegistry <name>

commandline.exe -describeSchemaRegistry production-registry

updateSchemaRegistry

Updates global Schema Registry mode and compatibility.

-updateSchemaRegistry <name> -mode READWRITE|READONLY|IMPORT -compatibility BACKWARD|BACKWARD_TRANSITIVE|FORWARD|FORWARD_TRANSITIVE|FULL|FULL_TRANSITIVE|NONE

commandline.exe -updateSchemaRegistry production-registry -mode READWRITE -compatibility BACKWARD_TRANSITIVE

deleteSchemaRegistry

Deletes a saved Schema Registry connection. A connection in use by a server connection cannot be deleted.

-deleteSchemaRegistry <name>

commandline.exe -deleteSchemaRegistry production-registry

addSubject

Adds version 1 of an AVRO or PROTOBUF Subject from a UTF-8 schema file.

-addSubject <Subject> -schemaRegistry <name> -schemaType AVRO|PROTOBUF -schemaFile <file>

commandline.exe -addSubject orders-value -schemaRegistry production-registry -schemaType AVRO -schemaFile C:\schemas\orders.avsc

listSubjects

Lists Subjects.

-listSubjects -schemaRegistry <name>

commandline.exe -listSubjects -schemaRegistry production-registry

describeSubject

Displays Subject type, mode, compatibility, server-config inheritance, and versions.

-describeSubject <Subject> -schemaRegistry <name>

commandline.exe -describeSubject orders-value -schemaRegistry production-registry

updateSubjectConfig

Updates Subject mode and compatibility. Use server to inherit the corresponding server-level setting.

-updateSubjectConfig <Subject> -schemaRegistry <name> -mode READWRITE|READONLY|IMPORT|server -compatibility BACKWARD|BACKWARD_TRANSITIVE|FORWARD|FORWARD_TRANSITIVE|FULL|FULL_TRANSITIVE|NONE|server

commandline.exe -updateSubjectConfig orders-value -schemaRegistry production-registry -mode server -compatibility FULL

deleteSubject

Deletes a Subject.

-deleteSubject <Subject> -schemaRegistry <name>

commandline.exe -deleteSubject orders-value -schemaRegistry production-registry

addSchemaVersion

Adds a version using a UTF-8 schema file.

-addSchemaVersion <Subject> -schemaRegistry <name> -schemaFile <file>

commandline.exe -addSchemaVersion orders-value -schemaRegistry production-registry -schemaFile C:\schemas\orders-v2.avsc

viewSchemaVersion

Displays Schema metadata and content for a version.

-viewSchemaVersion <Subject> -schemaRegistry <name> -version <number>

commandline.exe -viewSchemaVersion orders-value -schemaRegistry production-registry -version 2

deleteSchemaVersion

Deletes one Schema version.

-deleteSchemaVersion <Subject> -schemaRegistry <name> -version <number>

commandline.exe -deleteSchemaVersion orders-value -schemaRegistry production-registry -version 1

Kafka Connect Commands

addKafkaConnect

Adds a saved Kafka Connect connection.

-addKafkaConnect <name> -endpoint <URL> [-key <basic-auth user>] [-secret <basic-auth password>]

commandline.exe -addKafkaConnect production-connect -endpoint https://connect.example.com -key connect-user -secret connect-password

listKafkaConnects

Lists saved Kafka Connect connections.

-listKafkaConnects

commandline.exe -listKafkaConnects

describeKafkaConnect

Displays a saved connection name and endpoint.

-describeKafkaConnect <name>

commandline.exe -describeKafkaConnect production-connect

updateKafkaConnect

Updates a saved Kafka Connect connection. At least one optional value is required.

-updateKafkaConnect <name> [-newName <name>] [-endpoint <URL>] [-key <user>] [-secret <password>]

commandline.exe -updateKafkaConnect production-connect -newName connect-primary -endpoint https://connect2.example.com -key new-user -secret new-password

deleteKafkaConnect

Deletes a saved Kafka Connect connection.

-deleteKafkaConnect <name>

commandline.exe -deleteKafkaConnect connect-primary

listConnectorPlugins

Lists available Connector plugin class names, types, and versions.

-listConnectorPlugins -kafkaConnect <name>

commandline.exe -listConnectorPlugins -kafkaConnect production-connect

addConnector

Creates a Connector from a JSON configuration object. The file contains Connector properties, including connector.class, but not the outer Connector name.

-addConnector <Connector> -kafkaConnect <name> -configFile <JSON file>

commandline.exe -addConnector orders-source -kafkaConnect production-connect -configFile C:\connectors\orders-source.json

listConnectors

Lists Connector names, classes, and types.

-listConnectors -kafkaConnect <name>

commandline.exe -listConnectors -kafkaConnect production-connect

describeConnector

Displays Connector class, type, state, Worker, configuration, Tasks, and Topics.

-describeConnector <Connector> -kafkaConnect <name>

commandline.exe -describeConnector orders-source -kafkaConnect production-connect

deleteConnector

Deletes a Connector.

-deleteConnector <Connector> -kafkaConnect <name>

commandline.exe -deleteConnector orders-source -kafkaConnect production-connect

pauseConnector

Pauses a Connector.

-pauseConnector <Connector> -kafkaConnect <name>

commandline.exe -pauseConnector orders-source -kafkaConnect production-connect

resumeConnector

Resumes a paused Connector.

-resumeConnector <Connector> -kafkaConnect <name>

commandline.exe -resumeConnector orders-source -kafkaConnect production-connect

restartConnector

Restarts a Connector.

-restartConnector <Connector> -kafkaConnect <name>

commandline.exe -restartConnector orders-source -kafkaConnect production-connect

restartConnectorTask

Restarts one Connector Task.

-restartConnectorTask <Connector> -kafkaConnect <name> -task <number>

commandline.exe -restartConnectorTask orders-source -kafkaConnect production-connect -task 0

Back to overview