# Rudder CLI Tool


{{< announcement >}}
This feature is in **Public Beta**, where we work with early users and customers to test new features and get feedback before making them generally available.
{{< /announcement >}}

The Rudder CLI tool lets you manage multiple RudderStack resources as code, including [Tracking Plans and Data Catalog]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/" >}}), [Data Graphs]({{< ref "dev-tools/rudder-cli/manage-data-graphs.md" >}}), [SQL models for Reverse ETL]({{< ref "dev-tools/rudder-cli/sql-models/" >}}), [Event Stream sources]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}}), and [Transformations]({{< ref "dev-tools/rudder-cli/manage-transformations.md" >}}). It provides a complete command-line interface for working with your YAML-defined configurations, enabling Git-based workflows for collaboration and version control.

## Key features

This section highlights the key Rudder CLI features in terms of its core capabilities and usability.

### Core capabilities

- **Initialize and configure**: Set up your [Tracking Plan project structure]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/" >}}) with the necessary YAML templates.
- **Create, update, and delete**: Manage Data Catalog, Tracking Plan, Data Graph, and SQL model resources directly from your terminal.
- **Bi-directional management**: Create new resources from CLI or import existing resources from your workspace into Git.
- **Validation and preview**: Verify your YAML configurations locally, validate SQL syntax, and preview query results before pushing changes to production.
- **Remote synchronization**: Maintain consistency between your local files and your RudderStack workspace.

### Supported resource types

The Rudder CLI tool manages different types of resources through YAML configurations:

### Data governance

- **Event definitions**: Your events with names, descriptions, and categories
- **Property definitions**: Reusable properties with [validation rules]({{< ref "data-governance/data-catalog/properties.md#advanced-rules" >}}) like minimum/maximum length, patterns, enums, etc.
- **Tracking plan rules**: Associations between events and their required properties
- **Cross-references**: Reuse properties across multiple events using the path reference system

See [CLI-based Data Catalog and Tracking Plan Management]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/" >}}) for more details.

### Data Graphs

- **Data Graph definitions**: Define entities, events, and relationships in YAML files
- **Column metadata**: Add display names, descriptions, and PII masking settings for warehouse columns
- **Import and apply**: Bring existing Data Graph definitions under Git control and sync changes to your workspace

See [Manage Data Graphs using Rudder CLI]({{< ref "dev-tools/rudder-cli/manage-data-graphs.md" >}}) for more details.

### SQL models

- **SQL model definitions**: [Reverse ETL SQL model sources]({{< ref "data-pipelines/reverse-etl/features/models.md" >}}) with query logic, primary keys, and warehouse connections
- **External SQL files**: Reference external `.sql` files or define queries inline in YAML
- **Import existing resources**: Import existing SQL model resources from your workspace into Git

See [Manage SQL Models using Rudder CLI]({{< ref "dev-tools/rudder-cli/sql-models/" >}}) for more details.

### Event Stream sources

- **Event Stream source definitions**: [Event Stream sources]({{< ref "sources/event-streams/" >}}) with source type, name, and enabled status
- **Governance validation settings**: Associate [Tracking Plans]({{< ref "data-governance/tracking-plans/" >}}) with sources for data governance
- **Violation handling rules**: Control violation handling behavior for different event types (`track`, `identify`, `group`, `page`, `screen`) through granular configuration options

See [Manage Event Stream Sources using Rudder CLI]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}}) for more details.

### Transformations

- **Transformation and library specs**: Define `transformation` and `transformation-library` resources in YAML files
- **Inline or external code**: Write transformation code inline in YAML or reference external JavaScript/Python files
- **Local testing**: Run `rudder-cli transformations test` against fixtures before applying changes
- **Import and apply**: Bring existing workspace transformations under Git control

See [Manage Transformations using Rudder CLI]({{< ref "dev-tools/rudder-cli/manage-transformations.md" >}}) for more details.

### CI/CD integration

- **GitHub Actions support**: Integrate validation and deployment steps in your GitHub workflows.
- **Automated validation**: Run configuration checks as part of your CI pipeline.
- **Deployment automation**: Push validated Tracking Plans to production.

## Get started

Follow the steps in the below sections to get started with the Rudder CLI tool.

### Authenticate the CLI {#authenticate-the-cli}

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

### Choose your workflow

Choose your workflow based on the resources you want to manage:

{{< tabs tabTotal="5" >}}
{{% tab tabName="Tracking Plans and Data Catalog" %}}

1. [Install the Rudder CLI tool]({{< ref "dev-tools/rudder-cli/installation.md" >}}) in your preferred environment.
2. [Authenticate the CLI](#authenticate-the-cli) with an access token with the [relevant permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage Data Catalog and Tracking Plans.
3. [Initialize a new Tracking Plan project]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/" >}}) with [YAML definitions]({{< ref "dev-tools/rudder-cli/yaml-data-catalog-and-tracking-plans/" >}}). Then, sync the changes to your workspace.
4. Automate Tracking Plan management using [GitHub Actions]({{< ref "dev-tools/rudder-cli/github-actions/" >}}).

See [CLI-based Data Catalog and Tracking Plan Management]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/" >}}) for more details.
{{% /tab %}}
{{% tab tabName="Data Graphs" %}}

1. [Install the Rudder CLI tool]({{< ref "dev-tools/rudder-cli/installation.md" >}}) in your preferred environment.
2. [Authenticate the CLI](#authenticate-the-cli) with an access token with the [relevant permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage Data Graphs.
3. Define Data Graph resources using the [Data Graph YAML Reference]({{< ref "dev-tools/rudder-cli/data-graph.md" >}}).
4. Apply changes to your workspace using `rudder-cli apply`.

See [Manage Data Graphs using Rudder CLI]({{< ref "dev-tools/rudder-cli/manage-data-graphs.md" >}}) for more details.
{{% /tab %}}
{{% tab tabName="SQL Models" %}}

1. [Install the Rudder CLI tool]({{< ref "dev-tools/rudder-cli/installation.md" >}}) in your preferred environment.
2. [Authenticate the CLI](#authenticate-the-cli) with an access token with the [relevant permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage SQL models.
3. Set up your project directory and [create new SQL model resources]({{< ref "dev-tools/rudder-cli/sql-models/create.md" >}}) or [import existing ones]({{< ref "dev-tools/rudder-cli/sql-models/import.md" >}}) from your workspace.
4. [Validate and preview]({{< ref "dev-tools/rudder-cli/sql-models/validate.md" >}}) your SQL models before deployment.
5. Automate SQL model management using [GitHub Actions]({{< ref "dev-tools/rudder-cli/github-actions/" >}}).

See [Manage SQL Models using Rudder CLI]({{< ref "dev-tools/rudder-cli/sql-models/" >}}) for more details.
{{% /tab %}}
{{% tab tabName="Event Stream Sources" %}}

1. [Install the Rudder CLI tool]({{< ref "dev-tools/rudder-cli/installation.md" >}}) in your preferred environment.
2. [Authenticate the CLI](#authenticate-the-cli) with an access token with the [relevant permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage Event Stream sources.
3. [Create new Event Stream sources]({{< ref "dev-tools/rudder-cli/event-stream-sources-walkthrough.md" >}}) in your workspace.
4. [Validate and deploy]({{< ref "dev-tools/rudder-cli/event-stream-sources-walkthrough.md#6-validate-and-deploy" >}}) your Event Stream sources.

See [Manage Event Stream Sources using Rudder CLI]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}}) for more details.
{{% /tab %}}
{{% tab tabName="Transformations" %}}

1. [Install the Rudder CLI tool]({{< ref "dev-tools/rudder-cli/installation.md" >}}) in your preferred environment.
2. [Authenticate the CLI](#authenticate-the-cli) with an access token with the [relevant permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage Transformations.
3. Create transformation YAML specs with inline code or references to external JavaScript/Python files.
4. [Test transformations locally]({{< ref "dev-tools/rudder-cli/transformations-walkthrough.md#6-test-transformations-locally" >}}) using `rudder-cli transformations test`.
5. Apply changes to your workspace using `rudder-cli apply`.

See [Manage Transformations using Rudder CLI]({{< ref "dev-tools/rudder-cli/manage-transformations.md" >}}) for more details.
{{% /tab %}}
{{< /tabs >}}

<br />