Skip to main content

Command line tool (fda)

fda is a command line utility for interacting with the Feldera Manager's REST API. It allows you to create, manage, and monitor pipelines. It also features an interactive shell for inspecting and modifying the state of tables and views using SQL commands.

Installation​

Quick Install​

curl -fsSL 'https://docs.feldera.com/install-fda' | bash
Supported platforms
linux-x86_64
linux-aarch64

Requires glibc >= 2.39 (Ubuntu 24.04+, Debian 13+, Fedora 40+, RHEL 10+).

Installing a Specific Version​

Since fda is a single binary, you can update or install older versions by re-running the installer script.

To install a specific version, pass the release git tag to the install script:

curl -fsSL 'https://docs.feldera.com/install-fda' | FDA_VERSION=v0.290.0 bash

To install to a custom directory:

curl -fsSL 'https://docs.feldera.com/install-fda' | FDA_VERSION=v0.290.0 FELDERA_INSTALL=/opt/feldera bash

Using Cargo (other platforms)​

To install fda with Cargo, you need a working Rust environment. You can install Rust by following the instructions on the Rust website.

Run the following command to install fda as a Rust crate:

cargo install fda

Alternatively, to build and install the latest fda revision from our main git branch, run the following command:

cargo install --git https://github.com/feldera/feldera fda

To build from the sources in your local feldera repository, you can install fda with the following commands:

cd crates/fda
cargo install --path .

Optional: Shell completion​

Once the fda binary is installed, you can enable shell command completion for fda by adding the following line to your shell init script.

# Bash
echo "source <(COMPLETE=bash fda)" >> ~/.bashrc

# Elvish
echo "eval (COMPLETE=elvish fda)" >> ~/.elvish/rc.elv

# Fish
echo "source (COMPLETE=fish fda | psub)" >> ~/.config/fish/config.fish

# Zsh
echo "source <(COMPLETE=zsh fda)" >> ~/.zshrc

Connecting & Authentication​

To connect to the Feldera manager, you need to provide the URL of the manager. You can either provide the URL as an environment variable or as a command line argument. The environment variable is called FELDERA_HOST and the command line argument is called --host.

If your Feldera instance requires authentication (not needed in the local docker form factor), you'll also need to provide an API key. You can either set the API key as an environment variable or as a command line argument. The environment variable is called FELDERA_API_KEY and the command line argument is called --auth. It is recommended to use an environment variable configured in your shell init script to avoid storing the API key in your shell history.

info

You can create a new API key by logging into the Feldera WebConsole. Once logged in, click on your profile in the top right. Go to Manage API Keys and click Generate new key.

Authenticating with a short-lived token​

Workloads can use short lived bearer tokens from a file, typically an OIDC identity token that the platform rotates: a Kubernetes service-account token, or the one feldera/oidc-auth-action keeps current for a GitHub Actions job. The environment variable FELDERA_OIDC_TOKEN_FILE and the command line argument --oidc-token-file both take the path to that file.

fda --host https://feldera.internal --oidc-token-file /var/run/secrets/kubernetes.io/serviceaccount/token pipelines
# or via environment:
export FELDERA_OIDC_TOKEN_FILE="$AWS_WEB_IDENTITY_TOKEN_FILE"
fda --host https://feldera.internal pipelines

The instance accepts such a token only where an OIDC trust matches its issuer, subject and audience; see fda oidc-trust create --help. --oidc-token-file and --auth are mutually exclusive.

Connecting to HTTPS with a custom CA​

When the Feldera manager is served over HTTPS with a certificate issued by a private CA, or with a self-signed certificate, fda needs to trust that CA before it can talk to the manager. The environment variable FELDERA_HTTPS_TLS_CERT and the command line argument --tls-cert both take a path to a PEM-encoded certificate file. The file may contain one or more certificates; every certificate in the bundle is added to the client's set of trusted roots:

fda --host https://feldera.internal --tls-cert /etc/ssl/ca-bundle.pem pipelines
# or via environment:
export FELDERA_HTTPS_TLS_CERT=/etc/ssl/ca-bundle.pem
fda --host https://feldera.internal pipelines

--tls-cert extends the trust store while keeping certificate verification on, so it is the preferred option for reaching HTTPS endpoints with custom CAs. The separate --insecure / -k flag disables verification entirely and should only be used for local testing. --tls-cert and --insecure are mutually exclusive; passing both on the same invocation is rejected by fda.

Examples​

Specify the host and API key as command line arguments or environment variables:

fda --host https://try.feldera.com --auth apikey:0aKFj50iE... pipelines
export FELDERA_HOST=https://try.feldera.com
export FELDERA_API_KEY=apikey:0aKFj50iE...
fda pipelines

Create a new pipeline p1 from a program.sql file:

echo "CREATE TABLE example ( id INT NOT NULL PRIMARY KEY );
CREATE VIEW example_count AS ( SELECT COUNT(*) AS num_rows FROM example );" > program.sql
fda create p1 program.sql

Copy pipeline p1 to a new pipeline p2:

fda copy p1 p2

Enable storage for p1:

fda set-config p1 storage true

View and set the tags of p1:

fda tags p1                        # prints the tags as a comma-separated list
fda set-tags p1 prod,team-billing
fda set-tags p1 `fda tags p1`,qa   # append to the existing tags
fda set-tags p1                    # clear all tags

Add Rust UDF code to p1:

fda program set p1 --udf-toml udf.toml --udf-rs udf.rs

Run the pipeline p1:

fda start p1

Start a transaction for p1:

fda start-transaction p1

Commit a transaction for p1:

fda commit-transaction p1

Retrieve the stats for p1:

fda stats p1

Retrieve the latest log messages for p1:

fda logs p1

Download the support bundle for p1:

fda support-bundle p1

Shutdown and delete the pipeline p1:

fda shutdown p1
fda delete p1

Execute ad-hoc SQL query:

fda exec pipeline-name "SELECT * FROM materialized_view;"
cat query.sql | fda exec pipeline-name -s

Shell​

You can enter the fda shell for a pipeline by running the following command:

fda shell p1

Within the shell, you can interact with the pipeline p1 by sending ad-hoc SQL queries to it.

The shell also lets you execute certain CLI commands like start, restart, shutdown without having to provide the pipeline name every time. Type help for more information.