# End-to-End Walkthrough: Destinations with Rudder CLI


This tutorial shows you how to use [Rudder CLI]({{< ref "dev-tools/rudder-cli/" >}}) to:

- Authenticate against your RudderStack workspace
- Enable experimental destination support
- Create a project directory and define an Amazon S3 destination in YAML
- Validate and deploy the destination to your workspace

For feature overview and supported types, see [Manage Destinations using Rudder CLI]({{< ref "dev-tools/rudder-cli/destinations.md" >}}). To wire the destination to a source, continue with the [Connections walkthrough]({{< ref "dev-tools/rudder-cli/connections-walkthrough.md" >}}).

## Prerequisites

- Rudder CLI tool (`rudder-cli`) [installed locally]({{< ref "dev-tools/rudder-cli/installation.md" >}})
- In your RudderStack workspace, create a [workspace-level Service Access Token]({{< ref "access-management/service-access-tokens.md#workspace-sat" >}}) with the following [permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage destinations:

| Resource | Permissions | <div style="width:350px">Description</div> |
| :----| :-----| :----|
| Destinations | **Create & Delete** | Create or delete destinations in the workspace |
| Destinations | **Edit** | Change destination configuration |
| Destinations | **Connect** | Connect a destination to a source or a transformation |

{{< customreadfile "/includes/rudder-cli/token-auth-footer-admin.md" >}}

## 1. Authenticate the CLI tool

{{< customreadfile "/includes/rudder-cli/auth-login-step.md" >}}

## 2. Enable destination support

Destination resources are experimental. Enable the `destinationSupport` flag so Rudder CLI registers the `destination` kind.

Set the flag in your environment (or the equivalent key in your CLI configuration):

```shell
export RUDDERSTACK_X_DESTINATION_SUPPORT=true
```

This tutorial uses Amazon S3. See [Supported destination types]({{< ref "dev-tools/rudder-cli/yaml-destinations.md#supported-destination-types" >}}) for the destinations you can define with Rudder CLI.

{{< customreadfile "/includes/rudder-cli/unverified-destinations-later.md" >}}

If you use access-key authentication, see [How to Use Variable Substitution in Rudder CLI]({{< ref "dev-tools/rudder-cli/variable-substitution.md" >}}). This tutorial uses IAM role authentication, so you don't need a var file.

## 3. Create a project directory

Create a project directory to store your destination YAML files:

```shell
mkdir ~/tutorial-destinations
```

{{< info >}}
If you already manage Event Stream sources or other CLI resources, add the destination file to the same project directory. Rudder CLI processes all YAML files in the directory recursively.
{{< /info >}}

## 4. Review the YAML reference

Before you define the destination, review the [Destination YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-destinations.md" >}}) for:

- The `destination` spec envelope (`id`, `display_name`, `type`, `definition_version`, `enabled`, `config`)
- Amazon S3 `config` keys, including role-based vs access-key authentication
- How `display_name` uniqueness and `type` immutability work

## 5. Define an Amazon S3 destination

Create `~/tutorial-destinations/s3.yaml`:

```yaml
version: rudder/v1
kind: destination
metadata:
  name: s3
spec:
  id: s3
  display_name: "S3 Destination"
  type: s3
  definition_version: 1
  enabled: true
  config:
    bucket_name: "my-rudder-bucket"
    prefix: "rudder-events"
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>"
```

Replace `<AWS_ACCOUNT_ID>` and `<ROLE_NAME>` with values from your AWS account. `role_based_auth` is required. When it is `true`, you must set `iam_role_arn` and must not set access keys.

{{< info >}}
`id` is the project identifier other specs use in `#destination:s3` references. `display_name` is what the dashboard shows and must be unique among destinations in the project.
{{< /info >}}

## 6. Validate and deploy

1. Validate your files:

```shell
rudder-cli validate -l ~/tutorial-destinations
```

2. **Optional**: Preview the workspace changes:

```shell
rudder-cli apply -l ~/tutorial-destinations --dry-run
```

3. Deploy the destination:

```shell
rudder-cli apply -l ~/tutorial-destinations
```

## See more

- [Manage Destinations using Rudder CLI]({{< ref "dev-tools/rudder-cli/destinations.md" >}})
- [Destination YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-destinations.md" >}})
- [How to Use Variable Substitution in Rudder CLI]({{< ref "dev-tools/rudder-cli/variable-substitution.md" >}})
- [End-to-End Walkthrough: Connections with Rudder CLI]({{< ref "dev-tools/rudder-cli/connections-walkthrough.md" >}})
- [GitHub Actions for Rudder CLI]({{< ref "dev-tools/rudder-cli/github-actions" >}})