Install Rudder CLI

Rudder CLI is an agent-first, command-line interface tool designed to interact with RudderStack’s services, facilitating tasks like CLI-based configuration, management, and deployment of Tracking Plans and Data Catalog. See CLI-based Data Catalog and Tracking Plan Management for more information on this feature.

Rudder CLI releases follow semantic versioning. Changes that require editing specs, flags, or workflows land only in a major release and are recorded in BREAKING_CHANGES.md.

Install Rudder CLI

This section contains the Rudder CLI installation steps for the currently supported platforms.

One-line install

On macOS or Linux, install the latest release:

curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/latest/download/install.sh | sh

Each release from v0.29.0 on publishes its own installer. Pin v1.0.0 with:

curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/download/v1.0.0/install.sh | sh

Note that:

• For about five minutes after a release is published, its files are still uploading and the latest-release command returns a 404. Run it again after the upload finishes.
• The script selects the archive for your operating system and CPU, checks it against the release checksums, and installs rudder-cli into ~/.local/bin without sudo. It runs the new binary once before replacing an existing one, so a release that cannot run on your system leaves the current binary in place. If ~/.local/bin is not on your PATH, the script prints the line to add to your shell profile.

The macOS and Linux steps below install into /usr/local/bin. If that copy appears earlier on your PATH than ~/.local/bin, that copy is the binary that runs. The script names it and prints the profile line that puts ~/.local/bin first.

Set RUDDER_CLI_VERSION or RUDDER_CLI_INSTALL_DIR on the sh side of the pipe. RUDDER_CLI_VERSION selects a release, such as 1.0.0 or v1.0.0, including releases from before v0.29.0. RUDDER_CLI_INSTALL_DIR selects the installation directory.

curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/latest/download/install.sh | RUDDER_CLI_VERSION=1.0.0 RUDDER_CLI_INSTALL_DIR="$HOME/bin" sh

The script does not support Windows. Download the .zip for your CPU from the latest release.

macOS

You can install the Rudder CLI on macOS devices depending on your chip configuration:

curl -L https://github.com/rudderlabs/rudder-iac/releases/latest/download/rudder-cli_Darwin_arm64.tar.gz | tar -xz rudder-cli
sudo mv rudder-cli /usr/local/bin/

curl -L https://github.com/rudderlabs/rudder-iac/releases/latest/download/rudder-cli_Darwin_x86_64.tar.gz | tar -xz rudder-cli
sudo mv rudder-cli /usr/local/bin/

Linux

Run the following command to install Rudder CLI on Linux:

curl -L https://github.com/rudderlabs/rudder-iac/releases/latest/download/rudder-cli_Linux_x86_64.tar.gz | tar -xz rudder-cli
sudo mv rudder-cli /usr/local/bin/

Docker

You can run the CLI directly using Docker:

docker run rudderlabs/rudder-cli

If you need to persist your configuration or provide an external configuration file, you can mount your local configuration directory into the container.

Assuming your configuration directory is located at ~/.rudder, you can run the following command:

docker run -v ~/.rudder:/.rudder rudderlabs/rudder-cli

To run commands with local catalog files, mount your files directory and use the -l flag. For example:

docker run -v ~/.rudder:/.rudder -v ~/my-catalog:/catalog rudderlabs/rudder-cli tp apply --dry-run -l /catalog

The above command uses the access token from your local configuration file and the Catalog files from the /catalog directory.

You can also use the RUDDERSTACK_ACCESS_TOKEN environment variable to provide the access token, as shown:

docker run -v ~/my-catalog:/catalog -e RUDDERSTACK_ACCESS_TOKEN=your-access-token rudderlabs/rudder-cli tp apply --dry-run -l /catalog

Build from source

Make sure to have Go installed and set up in your environment before following the steps in this section.

Run the following commands in order:

git clone https://github.com/rudderlabs/rudder-iac.git
cd rudder-iac
make build
sudo mv bin/rudder-cli /usr/local/bin/

To build the Docker image locally:

make docker-build