Spec Version:

Rudder CLI Tool Beta

Use RudderStack’s CLI tool to manage Tracking Plans, Data Catalog, Data Graphs, SQL models, and Transformations as code.
Available Plans
  • free
  • growth
  • enterprise

  •   5 minute read  

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.

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:

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

  1. Install the Rudder CLI tool in your preferred environment.
  2. Authenticate the CLI with an access token with the relevant permissions to manage Data Catalog and Tracking Plans.
  3. Initialize a new Tracking Plan project with YAML definitions. Then, sync the changes to your workspace.
  4. Automate Tracking Plan management using GitHub Actions.

See CLI-based Data Catalog and Tracking Plan Management for more details.

  1. Install the Rudder CLI tool in your preferred environment.
  2. Authenticate the CLI with an access token with the relevant permissions to manage Data Graphs.
  3. Define Data Graph resources using the Data Graph YAML Reference.
  4. Apply changes to your workspace using rudder-cli apply.

See Manage Data Graphs using Rudder CLI for more details.

  1. Install the Rudder CLI tool in your preferred environment.
  2. Authenticate the CLI with an access token with the relevant permissions to manage SQL models.
  3. Set up your project directory and create new SQL model resources or import existing ones from your workspace.
  4. Validate and preview your SQL models before deployment.
  5. Automate SQL model management using GitHub Actions.

See Manage SQL Models using Rudder CLI for more details.

  1. Install the Rudder CLI tool in your preferred environment.
  2. Authenticate the CLI with an access token with the relevant permissions to manage Event Stream sources.
  3. Create new Event Stream sources in your workspace.
  4. Validate and deploy your Event Stream sources.

See Manage Event Stream Sources using Rudder CLI for more details.

  1. Install the Rudder CLI tool in your preferred environment.
  2. Authenticate the CLI with an access token with the relevant permissions to manage Transformations.
  3. Create transformation YAML specs with inline code or references to external JavaScript/Python files.
  4. Test transformations locally using rudder-cli transformations test.
  5. Apply changes to your workspace using rudder-cli apply.

See Manage Transformations using Rudder CLI for more details.


Questions? We're here to help.

Join the RudderStack Slack community or email us for support

Slack Join now → Email Reach out →