Spec Version: v1 (Latest)v0.1

Rudder CLI Tool Beta

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.

The Rudder CLI tool lets you manage multiple RudderStack resources as code, including Tracking Plans and Data Catalog, Data Graphs, SQL models for Reverse ETL, Event Stream sources, and Transformations. 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 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 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 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 for more details.

SQL models

• SQL model definitions: Reverse ETL SQL model sources 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 for more details.

Event Stream sources

• Event Stream source definitions: Event Stream sources with source type, name, and enabled status
• Governance validation settings: Associate 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 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 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

Run rudder-cli auth login and enter one of the following when prompted:

• Workspace-level Service Access Token: RudderStack recommends this for production and CI/CD. Note that the token must have the relevant permissions to manage the relevant resources.
• Personal Access Token with Read-Write role: Use this for local development, or if you’re on Free or self-hosted plan.

Any action authenticated by a Personal Access Token will break if the user generating the token is removed from the organization or there is a breaking change to their permissions.

Choose your workflow

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