# End-to-End Walkthrough: Event Stream Sources with Rudder CLI


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

- Authenticate against your RudderStack workspace
- Create a project directory and define an Event Stream source in YAML
- Optionally attach a Tracking Plan for data governance
- Validate and deploy the source to your workspace

For feature overview and supported source types, see [Manage Event Stream Sources using Rudder CLI]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}}).

## Prerequisites

- Rudder CLI tool (`rudder-cli`) [installed locally]({{< ref "dev-tools/rudder-cli/installation.md" >}})
- An existing [Tracking Plan]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/" >}}) defined in your CLI project (optional, but **recommended** for [Data Governance]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/" >}}))
- 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 Event Stream sources:

| Resource | Permissions | <div style="width:350px">Description</div> |
| :----| :-----| :----|
| Event Stream Sources | **Create & Delete** | Create or delete Event Stream sources in the workspace |
| Event Stream Sources | **Edit** | Make changes to the configuration of Event Stream sources |
| Event Stream Sources | **Connect** | Connect an Event Stream source to a Tracking Plan |
| Tracking Plans | **Edit**, **Connect** | Connect a Tracking Plan to an Event Stream source |

{{< details "**Click here to see how these permissions appear in the workspace policy**." >}}
<br />

{{< figure src="images/access-management/rudder-cli-event-stream.webp" alt="Permissions to manage Event Stream sources in RudderStack dashboard" >}}

{{< /details >}}
<br />

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

## 1. Authenticate the CLI tool

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

## 2. Create a project directory

Create a project directory to store your source YAML files:

```shell
mkdir ~/tutorial-sources
```

{{< info >}}
If you are already managing Tracking Plans or Data Catalog resources via CLI, you can add source definitions to the same project directory. The CLI processes all YAML files in the directory recursively.
{{< /info >}}

## 3. Review the YAML reference

Before defining your Event Stream source, review the [Source YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-event-stream-sources" >}}) to understand:

- The complete YAML structure for Event Stream sources
- Required and optional fields for source configuration
- Governance validation settings and violation rules
- Reference syntax for linking sources to Tracking Plans

{{< success >}}
Understanding the YAML reference will help you create properly structured files and avoid common validation errors when defining your sources.
{{< /success >}}

## 4. Define an Event Stream source

Create a YAML file for your Event Stream source (`~/tutorial-sources/ios-source.yaml`):

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: ios-source
spec:
  id: "my-ios-source"
  type: "ios"
  name: "iOS Source"
  enabled: true
```

This example creates a basic iOS source without governance configuration. The source accepts events and is enabled by default.

## 5. Optional: Add governance configuration

If you want to associate a Tracking Plan with your source for data governance, update the YAML file to include governance settings:

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: ios-source
spec:
  id: "my-ios-source"
  type: "ios"
  name: "iOS Source"
  enabled: true
  governance:
    validations:
      tracking_plan: "#tracking-plan:my-tracking-plan"
      config:
        track:
          propagate_violations: true
          drop_unplanned_events: true
          drop_unplanned_properties: true
          drop_other_violations: true
        identify:
          propagate_violations: true
          drop_unplanned_properties: true
          drop_other_violations: true
```

In this example:

- The source is linked to a Tracking Plan referenced as `#tracking-plan:my-tracking-plan`.
- For `track` events, violations are propagated, unplanned events are dropped, unplanned properties are dropped, and other violations are dropped.
- For `identify` events, violations are propagated, unplanned properties are dropped, and other violations are dropped.

{{< info >}}
The Tracking Plan reference follows the format `#tracking-plan:[tracking-plan.id]`, where `tracking-plan.id` is the `spec.id` value of the Tracking Plan.

See [Source YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-event-stream-sources" >}}) for detailed information about these configuration options.
{{< /info >}}

## 6. Validate and deploy

1. Validate your files:

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

2. **Optional**: Review changes before deploying:

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

3. Deploy changes to your workspace:

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

## See more

- [Manage Event Stream Sources using Rudder CLI]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}})
- [Event Stream Sources YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-event-stream-sources" >}})
- [GitHub Actions for Rudder CLI]({{< ref "dev-tools/rudder-cli/github-actions" >}})