Fluvio CLI

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.

Download and Install 

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:

CLI Overview 

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.

Modules 

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 
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:

  • spu
  • spu-group
  • custom-spu
  • topic

However, there are a few exceptions:

  • consume/produce
  • advanced

“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.

Operations 

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.

Options / Flags 

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.

Target Service 

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.

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

Default Profile

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:
Related Topics