# Install Rudder CLI


> Install the Rudder CLI tool in your preferred environment.



[Rudder CLI](https://github.com/rudderlabs/rudder-iac) 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](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/) for more information on this feature.

Rudder CLI releases follow [semantic versioning](https://semver.org). Changes that require editing specs, flags, or workflows land only in a major release and are recorded in [BREAKING_CHANGES.md](https://github.com/rudderlabs/rudder-iac/blob/main/BREAKING_CHANGES.md).

<!-- REVIEW(DOCS) — confirm the semver commitment against a pending breaking change.

rudder-iac/BREAKING_CHANGES.md has an "Upcoming (unreleased)" section containing
a breaking change: secret references in imported specs become single-quoted
('{{ .VAR }}'), which requires users to hand-edit JSON secret references and
double single quotes in var files.

Under the policy stated above, that must ship in 2.0.0 or be reclassified as
non-breaking. Please confirm before this stability language goes live, since it
is a public commitment. Pending confirmation from @shanmukh.
-->

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

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

```bash
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.

**Warning:** 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.

```bash
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](https://github.com/rudderlabs/rudder-iac/releases/latest).

### macOS

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

#### Apple Silicon

```bash
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/
```
#### Intel-based

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

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

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

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

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

```bash
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

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

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

```bash
make docker-build
```

<br />