Fluvio CLI Reference
This page is the detailed reference for all the commands in the Fluvio CLI.
Most of the information given here can also be found in the help menu for
Fluvio, fluvio help, but here we will also explain when you may want to
use certain commands and show some examples.
Here is a list of all Fluvio commands that are available by default:
fluvio topic create
This command is used to create new Fluvio topics. A Fluvio topic is a stream where
you send related messages. Different topics have unique names and store their data
independently. They may also be divided into multiple partitions, which can
increase the message throughput of the topic.
Create a Topic with the given name
fluvio topic create [FLAGS] [OPTIONS] <name>
FLAGS:
-i, --ignore-rack-assignment
Ignore racks while computing replica assignment
-d, --dry-run Validates configuration, does not provision
-h, --help Prints help information
OPTIONS:
-p, --partitions <partitions>
The number of Partitions to give the Topic [default: 1]
-r, --replication <integer>
The number of full replicas of the Topic to keep [default: 1]
-f, --replica-assignment <file.json> Replica assignment file
ARGS:
<name> The name of the Topic to create
Example usage:
$ fluvio topic create greeting
topic "greeting" created
fluvio topic list
This command shows you all the existing topics in your cluster, as well as some basic
information about them, including how many partitions a topic has and how many times it
is replicated.
List all of the Topics in the cluster
fluvio topic list [OPTIONS]
FLAGS:
-h, --help Prints help information
OPTIONS:
-O, --output <type> Output [default: table] [possible values: table,
yaml, json]
Example usage:
$ fluvio topic list
NAME TYPE PARTITIONS REPLICAS IGNORE-RACK STATUS REASON
greeting computed 1 1 resolution::provisioned
fluvio topic describe
This command prints more detailed information about a specific topic.
Print detailed information about a Topic
fluvio topic describe [OPTIONS] <name>
FLAGS:
-h, --help Prints help information
OPTIONS:
-O, --output <type> Output [default: table] [possible values: table,
yaml, json]
ARGS:
<name> The name of the Topic to describe
Example usage:
$ fluvio topic describe greeting
Name : greeting
Type : computed
Partition Count : 1
Replication Factor : 1
Ignore Rack Assignment : false
Status : provisioned
Reason :
-----------------
fluvio topic delete
This command deletes an existing Fluvio topic and all data associated with it.
This data may not be recovered, so use this with care.
Delete a Topic with the given name
fluvio topic delete <name>
FLAGS:
-h, --help Prints help information
ARGS:
<name> The name of the Topic to delete
Example usage:
$ fluvio topic delete greeting
topic "greeting" deleted
fluvio partition list
Prints basic information about each partition in the cluster, such as
which topic it belongs to, which SPU is leading the partition, and the
various offsets the partition keeps track of.
List all of the Partitions in this cluster
fluvio partition list [OPTIONS]
FLAGS:
-h, --help Prints help information
OPTIONS:
-O, --output <type> Output [default: table] [possible values: table,
yaml, json]
Example usage:
$ fluvio partition list
TOPIC PARTITION LEADER REPLICAS RESOLUTION HW LEO LSR FOLLOWER OFFSETS
greeting 0 5001 [] Online 1 1 0 []
fluvio produce
The fluvio produce command is a way to send messages to a particular topic and partition.
This can be useful for testing your applications by manually sending specific messages.
fluvio-produce 0.4.0
Write messages to a topic/partition
By default, this reads a single line from stdin to use as the message. If you
run this with no file options, the command will hang until you type a line in
the terminal. Alternatively, you can pipe a message into the command like this:
$ echo "Hello, world" | fluvio produce greetings
USAGE:
fluvio produce [FLAGS] [OPTIONS] <topic>
FLAGS:
-C, --continuous Send messages in an infinite loop
-h, --help Prints help information
OPTIONS:
-p, --partition <integer>
The ID of the Partition to produce to [default: 0]
-l, --record-per-line <filename>
Send each line of the file as its own Record
-r, --record-file <filename>... Send an entire file as a single Record
ARGS:
<topic> The name of the Topic to produce to
By default, the fluvio produce command will read a single line from stdin and send it
as the payload of the message. However, you can also specify files to read messages from.
With the --record-per-line flag, you can send many messages from a single file, or with
the --record-file flag you can send the entire contents of a file (including newlines)
as a single record.
Example usage:
$ cat records.txt
{"user":"Bob","message":"Hello, Alice!"}
{"user":"Alice","message":"Hello, Bob!"}
$ fluvio produce my-topic --record-per-line records.txt
{"user":"Bob","message":"Hello, Alice!"}
{"user":"Alice","message":"Hello, Bob!"}
Ok!
You can then confirm that the records were sent by reading them back with fluvio consume:
$ fluvio consume my-topic -B -d
{"user":"Bob","message":"Hello, Alice!"}
{"user":"Alice","message":"Hello, Bob!"}
fluvio consume
The fluvio consume command is a way to read the contents of messages in a Fluvio topic
from a command-line environment. This can be useful if you are developing an application
with Fluvio and want real-time visibility into what is streaming through your topics.
It can also be handy for writing shell scripts that can read and react to messages in a
topic.
If your topic has more than one partition, the consume command will only read from one
of those partitions, defaulting to the first one (index zero). You can specify which
partition you want to read messages from using the -p option.
Arguments:
fluvio-consume 0.4.0
Read messages from a topic/partition
USAGE:
fluvio consume [FLAGS] [OPTIONS] <string>
FLAGS:
-B, --from-beginning Start reading from beginning
-d, --disable-continuous disable continuous processing of messages
-s, --suppress-unknown Suppress items items that have an unknown output
type
-h, --help Prints help information
OPTIONS:
-p, --partition <integer> Partition id [default: 0]
-o, --offset <integer>
Offsets can be positive or negative. (Syntax for negative offset:
--offset="-1")
-b, --maxbytes <integer> Maximum number of bytes to be retrieved
-O, --output <type>
Output [default: dynamic] [possible values: dynamic, text, binary,
json, raw]
ARGS:
<string> Topic name
Example usage:
Let’s say you want to read all the messages that have ever been produced for a particular
topic and partition, then stop when they have all been consumed. If our topic is named
“my-topic”, and we want to consume from partition 1, we can run:
fluvio consume my-topic -B -d -p 1
If you would like the consumer to continue running and print new messages as they arrive,
simply remove the -d flag:
fluvio consume my-topic -B -p 1
fluvio profile current
Prints out the name of the active Fluvio profile. Profiles are used to communicate with
different Fluvio clusters. For example, let’s say you have an application that uses
Fluvio Cloud, but you have a local Fluvio cluster installed that you use for development.
Each of those clusters would be represented by a profile, and whichever profile is “current”
is the one that the Fluvio CLI will interact with.
For example, if your Fluvio Cloud profile is called “cloud”, and your local profile is called
“local”, then if your current profile is “local”, then fluvio topic create greeting will
create a “greeting” topic on your local cluster.
fluvio-profile-current 0.4.0
Print the name of the current context
USAGE:
fluvio profile current
FLAGS:
-h, --help Prints help information
Example usage:
$ fluvio profile current
local
fluvio profile delete
Deletes a profile from your Fluvio configuration (~/.fluvio/config). This will
not delete a cluster (for that, see fluvio cluster delete), but it will cause
the Fluvio CLI to no longer be able to interact with that cluster.
fluvio-profile-delete 0.4.0
Delete the named profile
USAGE:
fluvio profile delete <profile name>
FLAGS:
-h, --help Prints help information
ARGS:
<profile name>
Example usage:
$ fluvio profile delete local
profile local deleted
If you try to delete the current profile, you will get a warning, because other CLI
commands depend on having a current profile being set.
$ fluvio profile delete local
profile local deleted
warning: this removed your current profile, use 'fluvio profile switch' to select a different one
fluvio profile delete-cluster
Deletes cluster connection information from your Fluvio configuration. This will not delete
a cluster itself (for that see fluvio cluster delete), but it will cause the Fluvio CLI to
no longer be able to connect to that cluster.
fluvio-profile-delete-cluster 0.4.0
Delete the named cluster
USAGE:
fluvio profile delete-cluster [FLAGS] <cluster name>
FLAGS:
-f, --force Deletes a cluster even if its active
-h, --help Prints help information
ARGS:
<cluster name> The name of a cluster connection to delete
Example usage:
$ fluvio profile delete-cluster local
Cluster local deleted
fluvio profile switch
This switches the “current” profile. After switching current profiles, all
subsequent Fluvio CLI commands that interact with a cluster will target the
cluster of the new “current” profile.
fluvio-profile-switch 0.4.0
Switch to the named profile
USAGE:
fluvio profile switch <profile name>
FLAGS:
-h, --help Prints help information
ARGS:
<profile name>
Example usage:
$ fluvio profile switch fluvio-cloud
fluvio profile view
This prints the entire Fluvio configuration (from ~/.fluvio/config).
fluvio-profile-view 0.4.0
Display the entire Fluvio configuration
USAGE:
fluvio profile view
FLAGS:
-h, --help Prints help information
Example usage:
$ fluvio profile view
Config {
version: "2.0",
current_profile: Some(
"minikube",
),
profile: {
"minikube": Profile {
cluster: "minikube",
topic: None,
partition: None,
},
},
cluster: {
"minikube": FluvioConfig {
addr: "10.111.134.218:9003",
tls: Disabled,
},
},
client_id: None,
}
fluvio cluster check
The cluster commands are used to install your own Fluvio cluster. This command
is used to check whether you have all the required dependencies set up on your
system and whether they are running correctly.
fluvio-cluster-check 0.4.2
Check that all requirements for cluster startup are met
USAGE:
fluvio cluster check
FLAGS:
-h, --help Prints help information
Example usage:
$ fluvio cluster check
Running pre-startup checks...
✅ ok: Kubernetes config is loadable
✅ ok: Supported kubernetes version is installed
✅ ok: Supported helm version is installed
✅ ok: Fluvio system charts are installed
✅ ok: Can create service
✅ ok: Can create customresourcedefinitions
✅ ok: Can create secret
✅ ok: Load balancer is up
All checks passed!
You may proceed with cluster startup
next: run `fluvio cluster start`
fluvio cluster start
This command is used to start your own Fluvio cluster, with all the
machinery needed to receive, process, and serve streaming messages.
There are two main variations of this command. The default variation
is invoked simply by fluvio cluster start. This will install Fluvio
to a Kubernetes cluster, typically Minikube. The other variation is
fluvio cluster start --local, which will start the cluster components
as plain processes on your local machine.
fluvio-cluster-start 0.4.2
Start a Fluvio cluster, locally or on Minikube
USAGE:
fluvio cluster start [FLAGS] [OPTIONS]
FLAGS:
--develop use local image
--skip-profile-creation
--sys installing sys
--local install local spu/sc(custom)
--tls Whether to use TLS
--skip-checks
Whether to skip pre-install checks, defaults to false
--setup
Tries to setup necessary environment for cluster startup
-h, --help Prints help information
OPTIONS:
--chart-version <chart-version>
k8: use specific chart version [default: 0.6.0-beta.1]
--image-version <image-version>
k8: use specific image version
--registry <registry>
k8: use custom docker registry
--namespace <namespace>
k8 [default: default]
--group-name <group-name>
k8 [default: main]
--install-name <install-name>
helm chart installation name [default: fluvio]
--chart-location <chart-location>
Local path to a helm chart to install
--cloud <cloud>
k8 [default: minikube]
--spu <spu>
number of SPU [default: 1]
--rust-log <rust-log>
RUST_LOG options
--log-dir <log-dir>
log dir [default: /usr/local/var/log/fluvio]
--domain <domain> TLS: domain
--ca-cert <ca-cert> TLS: ca cert
--client-cert <client-cert>
TLS: client cert
--client-key <client-key> TLS: client key
--server-cert <server-cert>
TLS: path to server certificate
--server-key <server-key>
TLS: path to server private key
--authorization-config-map <authorization-config-map>
Example usage:
To start a cluster on Minikube:
$ fluvio cluster start
"fluvio" has been added to your repositories
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "jaegertracing" chart repository
...Successfully got an update from the "prometheus-community" chart repository
...Successfully got an update from the "fluvio" chart repository
Update Complete. ⎈Happy Helming!⎈
NAME: fluvio
LAST DEPLOYED: Mon Dec 28 13:12:27 2020
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
✅ ok: Kubernetes config is loadable
✅ ok: Supported helm version is installed
✅ ok: Fluvio system charts are installed
✅ ok: Previous fluvio installation not found
✅ ok: Load balancer is up
To start a cluster locally (as processes on your machine):
$ fluvio cluster start --local
Performing pre-flight checks
✅ ok: Supported helm version is installed
✅ ok: Supported kubernetes version is installed
✅ ok: Kubernetes config is loadable
✅ ok: Fluvio system charts are installed
fluvio cluster delete
Deletes a Fluvio cluster and all data associated with it. Be careful, this
cannot be undone.
fluvio-cluster-delete 0.4.2
Delete a Fluvio cluster from the local machine or Minikube
USAGE:
fluvio cluster delete [FLAGS] [OPTIONS]
FLAGS:
--no-wait don't wait for clean up
--local Remove local spu/sc(custom) fluvio installation
--sys Remove fluvio system chart
-h, --help Prints help information
OPTIONS:
--namespace <namespace> [default: default]
--name <name> [default: fluvio]
Example usage:
To uninstall Fluvio from Kubernetes (e.g. Minikube):
$ fluvio cluster delete
To uninstall Fluvio from your local machine:
$ fluvio cluster delete --local
fluvio cluster releases list
Prints all the published versions of Fluvio that are candidates to
install on Kubernetes with fluvio cluster start.
The Fluvio cluster components are distributed as Helm charts which allow
them to be installed easily on Kubernetes. This prints all the releases
that are available.
fluvio-cluster-releases-list 0.4.2
Show a list of Fluvio release versions
USAGE:
fluvio cluster releases list
FLAGS:
-h, --help Prints help information
Example usage:
$ fluvio cluster releases list
VERSION
0.6.0-latest
0.6.0-beta.1-latest
0.6.0-beta.1
0.6.0-alpha.8-latest
0.6.0-alpha.7-latest
...
fluvio cluster run sc
Directly invokes a Streaming Controller (SC) from the command line. This is a low-level
command and is not typically what you want to be using. If you want to run Fluvio
locally, check out the fluvio cluster start command and read about the --local
flag.
A Streaming Controller hosts a public server for interacting with clients, and a
private server for interacting with SPUs and other cluster components. Most of
the CLI options for the SC involve configuring these servers. See the
SC Architecture for more details.
fluvio-cluster-run-sc 0.2.0
Run a new Streaming Controller (SC)
USAGE:
fluvio cluster run sc [FLAGS] [OPTIONS]
FLAGS:
--tls enable tls
--enable-client-cert TLS: enable client cert
-h, --help Prints help information
OPTIONS:
--bind-public <bind-public>
Address for external service
--bind-private <bind-private>
Address for internal service
-n, --namespace <namespace>
--server-cert <server-cert>
TLS: path to server certificate
--server-key <server-key>
TLS: path to server private key
--ca-cert <ca-cert>
TLS: path to ca cert, required when client cert is enabled
--bind-non-tls-public <bind-non-tls-public>
TLS: address of non tls public service, required
--authorization-scopes <authorization scopes path>
[env: X509_AUTH_SCOPES=]
--authorization-policy <authorization policy path>
[env: AUTH_POLICY=]
fluvio cluster run spu
Directly invokes a Streaming Processing Unit (SPU) from the command line. This is a
low-level command and is not typically what you want to be using. If you want to run
Fluvio locally, check out the fluvio cluster start command and read about the --local
flag.
A SPU has a public server which is used to stream data to and from Fluvio Clients, and
a private server which is used to communicate with an SC. Most of the CLI options for
the SPU involve configuring these servers. See the SPU Architecture for more details.
fluvio-cluster-run-spu 0.2.0
Run a new Streaming Processing Unit (SPU)
USAGE:
fluvio cluster run spu [FLAGS] [OPTIONS]
FLAGS:
--tls enable tls
--enable-client-cert TLS: enable client cert
-h, --help Prints help information
OPTIONS:
-i, --id <integer> SPU unique identifier
-p, --public-server <host:port>
Spu server for external communication
-v, --private-server <host:port>
Spu server for internal cluster communication
--sc-addr <host:port>
Address of the SC Server [env: FLV_SC_PRIVATE_HOST=]
--log-base-dir <dir> [env: FLV_LOG_BASE_DIR=]
--log-size <log size> [env: FLV_LOG_SIZE=]
--index-max-bytes <integer>
[env: FLV_LOG_INDEX_MAX_BYTES=]
--index-max-interval-bytes <integer>
[env: FLV_LOG_INDEX_MAX_INTERVAL_BYTES=]
--peer-max-bytes <integer>
max bytes to transfer between leader and follower [env:
FLV_PEER_MAX_BYTES=] [default: 1000000]
--server-cert <server-cert>
TLS: path to server certificate
--server-key <server-key>
TLS: path to server private key
--ca-cert <ca-cert>
TLS: path to ca cert, required when client cert is enabled
--bind-non-tls-public <bind-non-tls-public>
TLS: address of non tls public service, required
fluvio install
Some Fluvio CLI commands are distributed as separate executables that we call
“extensions”. This command installs and updates extensions by name, placing
them in the ~/.fluvio/extensions/ directory.
fluvio-install 0.4.0
Install Fluvio plugins
The Fluvio CLI considers any executable with the prefix `fluvio-` to be a CLI
plugin. For example, an executable named `fluvio-foo` in your PATH may be
invoked by running `fluvio foo`.
This command allows you to install plugins from Fluvio's package registry.
USAGE:
fluvio install <package>
FLAGS:
-h, --help Prints help information
OPTIONS:
ARGS:
<package> The ID of a package to install, e.g. "fluvio/fluvio-cloud"
Example usage:
$ fluvio install fluvio/fluvio-cloud
🎣 Fetching latest version for package: fluvio/fluvio-cloud...
⏳ Downloading package with latest version: fluvio/fluvio-cloud:0.1.0...
🔑 Downloaded and verified package file
fluvio update
This command performs a self-update for the Fluvio CLI. It takes no arguments,
and just simply downloads the latest version of fluvio and overwrites itself.
Example usage:
$ fluvio update
🎣 Fetching latest version for fluvio/fluvio...
⏳ Downloading Fluvio CLI with latest version: fluvio/fluvio:0.6.0-beta.1...
🔑 Downloaded and verified package file
✅ Successfully installed ~/.fluvio/bin/fluvio
fluvio version
This command prints out the version of the Fluvio CLI that you’re running, as
well as some other useful information about how it was built. For example, it
includes the version of the Rust compiler used to build it as well as the exact
git commit of the Fluvio source code that was built. This is useful information
to include if you ever need to file a bug report so that the developers know
exactly what code needs fixing or if a fix is already available.
Example usage:
$ fluvio version
Fluvio CLI : 0.6.0-beta.1
Fluvio Platform : 0.6.0-beta.1
Git Commit : 68acd75c8d8c1a03ffa7512be5eb71fa6f79caa1
OS Details : Darwin 19.6.0 x86_64
Rustc Version : 1.48.0 (7eac88a 2020-11-16)