Fluvio Command Line Interface (CLI) is a powerful tool to deploy and manage your Fluvio services. One command line tool is all you need to control multiple Fluvio deployments and automate them through scripts.
Fluvio CLI has built-in Kafka compatibility which allows you to chain Fluvio and Kafka services from a unified command-line interface.
Fluvio command-line tool is available for Mac and Linux distributions and it can be used from the command prompt in your favorite terminal program.
Binaries are available for download at:
Fluvio CLI is user friendly and hierarchical. The syntax follows a well-defined pattern: fluvio, succeeded by module, operation and a series of options and flags. There are a couple of exceptions to this rule which are described later on.
Most options and flags are optional but there are some that are mandatory. Mandatory options are shown in the CLI usage line. For example, the syntax for Create a Topic is:
It shows that --topic, --partitions, and --replication, are mandatory.
Command line help is available at any level by appending -h or --help to the command. At top level, you can run fluvio with without arguments to get a list of available options.
Fluvio Command Line Interface fluvio <SUBCOMMAND> FLAGS: -h, --help Prints help information -V, --version Prints version information SUBCOMMANDS: consume Read messages from a topic/partition produce Write log records to a topic/partition spu SPU Operations spu-group SPU Group Operations custom-spu Custom SPU Operations topic Topic operations advanced Advanced operations help Prints this message or the help of the given subcommand(s)
Top level fluvio CLI is organized by modules:
However, there are a few exceptions:
“Consume/Produce” are kept at top level as they frequently used operations and we chose convenience over convention. “Advanced” is an aggregate of system-wide operations that don’t belong to any particular module.
Each module is followed by a series of operations that describe their capabilities. For example, topic module has the ability to create, list, describe, or delete topics:
$ fluvio topic
Topic operations fluvio topic <SUBCOMMAND> FLAGS: -h, --help Prints help information SUBCOMMANDS: create Create a topic delete Delete a topic describe Show details of a topic list Show all topics help Prints this message or the help of the given subcommand(s)
Other modules, such as spu have different options, hence different capabilities.
The modules are followed by options and flags. Options are composed of unique attributes, such as: -t, --topic, followed by modifiers. Flags are attributes without value.
Mandatory options are shown in the syntax definition. All other flags and options are optional.
$ fluvio topic create --help
Create a topic fluvio topic create [FLAGS] [OPTIONS] --partitions <integer> --replication <integer> --topic <string> FLAGS: -i, --ignore-rack-assignment Ignore racks while computing replica assignment -v, --validate-only Validates configuration, does not provision -h, --help Prints help information OPTIONS: -t, --topic <string> Topic name -p, --partitions <integer> Number of partitions -r, --replication <integer> Replication factor per partition -f, --replica-assignment <file.json> Replica assignment file -c, --sc <host:port> Address of Streaming Controller -k, --kf <host:port> Address of Kafka Controller -P, --profile <profile> Profile name
A small subset of the options, --kf, --sc, and --profile, are applied to every command. The purpose of these options is to help the CLI identify the location of the services where to send the command.
The Fluvio CLI is an independent binary that generates commands and sends them to a target service. Fluvio CLI can simultaneously manage multiple Fluvio and Kafka deployments.
The target service be specified through command line or profiles. The command line has higher precedence than profiles.
The profiles makes managing multiple deployments simple. A profile is a .toml configuration file that stores the location of the services. The syntax is as follows:
version = <profile-version> [sc] host = <hostname/ip> port = <port> [spu] host = <hostname/ip> port = <port> [kf] host = <hostname/ip> port = <port>
The parameters are as follows:
- version is currently set to “1.0”.
- hostname/ip is the location of the service, it may be a domain name or an IP address.
- port is the listening port of the service.
The most common configuration is one service per profile.
version = "1.0" [sc] host = "sc.fluvio.dev.acme.com" port = 9003
Fluvio CLI has one default profile and an unlimited number of user-defined profiles. The default profile has the lowest precedence and it is looked-up in the following order:
- command line parameter service (--sc, --spu, --kf),
- command line parameter user-defined profile (--profile).
- default profile
The CLI searches for the default.toml profile file in the following order:
- if $FLUVIO_HOME environment variable is set, look-up:
- if no environment variable is set, look-up: