Rudder CLI Tool

Use RudderStack’s CLI tool to create a tracking plan from scratch.

Available Plans

free
starter
growth
enterprise

8 minute read

This feature is part of RudderStack’s Early Access Program, where we work with early users and customers to test new features and get feedback before making them generally available. Note that these features are functional but can change as we improve them.
Make sure to contact the RudderStack team before using them in production.

This tutorial covers the steps for using the rudder-cli tool to create a tracking plan from scratch and deploy it to your RudderStack workspace.

Prerequisites

rudder-cli tool installed locally and available in your path.
In your RudderStack workspace, create a workspace-level Service Access Token or Personal Access Token (for testing purposes) with minimum read-write role.

1. Authenticate CLI tool

To use the CLI tool for working on your tracking plan, you need to first authenticate rudder-cli with the access token - this is required to perform operations on the target RudderStack workspace. Run the below command:

rudder-cli auth login

You will then see a prompt to enter your access token. Enter the token and press Enter to continue. Doing so stores the token locally and makes it available for all the future rudder-cli commands that need access to RudderStack.

The CLI maintains a local configuration file in your home directory (~/.rudder/config.json). After authentication, the configuration file will contain the unencrypted access token.

2. Prepare your data catalog project directory

The rudder-cli tool expects the data catalog resources to be described in YAML files present in your system. If you’re working with a Unix-compatible shell, run the following command to create a directory to contain these YAML files:

mkdir ~/tutorial-catalog

The above command creates a tutorial-catalog folder in your home directory, which you will use in this tutorial to start populating the data catalog files.

3. Create events

Before defining your tracking plan, you need to define the events you want to track. Using your preferred text editor, create a file ~/tutorial-catalog/my-events.yaml and add the following lines:

rudder-cli does not have any requirements for the file names or their location in the project directory, other than them having the yaml or .yml suffix. You can use any names or structure that makes sense for your project.

version: rudder/0.1
kind: events
metadata:
  name: myeventgroup
spec:
  events:
    - id: product_viewed
      display_name: "Product Viewed"
      event_type: track
      description: "This event is triggered every time a user views a product."

The above file defines an event you want to track in your application (Product Viewed). Before continuing, run the below command that validates the contents of the above file to make sure there are no issues:

rudder-cli tp validate -l ~/tutorial-project

Note that:

If the file has no errors, the command returns no output.
If there is any problem with the contents of the file, it outputs an error in the console.

4. Create properties

Each event in the tracking plan can be associated with various properties. Also, some properties might be shared across events. Create a file ~/tutorial-catalog/my-properties.yaml that defines the properties to track, as shown:

version: rudder/v0.1
kind: properties
metadata:
  name: mypropertygroup
spec:
  properties:
    - id: product_sku
      display_name: "SKU"
      type: string
      description: "Product SKU"
    - id: category
      display_name: "Category"
      type: string
      description: "Product's category"

This file defines two string properties that we can later associate with our Events, SKU and Category. Validate the project again using the same command (mentioned in Step 3):

rudder-cli tp validate -l ~/tutorial-project

Again, the command gives no output if there are no issues with the file’s content.

5. Create tracking plan

With both events and properties defined, you can now create a tracking plan that references them. Create a file ~/tutorial-catalog/my-tracking-plan.yaml and add the following:

version: rudder/0.1
kind: tp
metadata:
  name: mytrackingplan
spec:
  id: mytrackingplan
  display_name: "Product Tracking Plan"
  description: "Contains all the events and properties for the Product Tracking Plan."
  rules:
    - type: event_rule
      id: product_viewed_rule
      event:
        $ref: "#/events/myeventgroup/product_viewed"
      allow_unplanned: false
      properties:
        - $ref: "#/properties/mypropertygroup/product_sku"
          required: true
        - $ref: "#/properties/mypropertygroup/category"
          required: false

The above file defines a tracking plan that contains the event (Product Viewed) that we defined previously along with the properties (SKU and Category).

Note that you can associate the events and properties with the tracking plan by providing a reference to them using $ref. The references point to the specific entities defined in the project without strictly depending on the files they were defined in. Instead, they rely on the on the kind (events / properties), metadata.name and the entity’s id fields to uniquely refer to them.

For example, the Product Viewed event is defined with:

kind: events
metadata.name: myeventgroup
id: product_viewed

Therefore, you can refer to it using the #/events/myeventgroup/product_viewed reference.

Validate the tracking plan again before proceeding to the next step:

rudder-cli tp validate -l ~/tutorial-project

6. Deploy data catalog resources

With your events, properties, and tracking plan defined, deploy them to your RudderStack workspace.

Review the changes to ensure there are no mistakes by running the following command:

rudder-cli tp apply -l ~/tutorial-catalog --dry-run

The --dry-run option simulates the application of changes without making actual updates to your workspace. Instead, the rudder-cli tool reports all the resources as New resources, as seen in the below output:

New resources:
  - event:product_viewed
  - property:category
  - property:product_sku
  - tracking_plan:mytrackingplan

If the list matches your expectations, run the following command to apply the changes to your workspace:

rudder-cli tp apply -l ~/tutorial-catalog

The output will be similar, but with an additional confirmation prompt:

New resources:
  - event:product_viewed
  - property:category
  - property:product_sku
  - tracking_plan:mytrackingplan

? Do you want to apply these changes? (y/N)

Continue by typing y and pressing the Enter key. rudder-cli then starts creating the new resources one by one in your data catalog and reports if the process was successful, as shown:

✔ Create event:product_viewed
✔ Create property:category
✔ Create property:product_sku
✔ Create tracking_plan:mytrackingplan

7. Update tracking plan

In the above steps, you created and deployed a tracking plan containing rules for the Product Viewed event. You can use the rudder-cli tool to update the tracking plan by adding another event (Added to Cart) and property (price), and deploy the changes to your workspace.

Define a new event Added to Cart by opening the ~/tutorial-catalog/my-events.yaml file and adding the following content under spec.events:

version: rudder/0.1
kind: events
metadata:
  name: myeventgroup
spec:
  events:
    - id: product_viewed
      display_name: "Product Viewed"
      event_type: track
      description: "This event is triggered every time a user views a product."
    # New event added here
    - id: added_to_cart
      display_name: "Added To Cart"
      event_type: track
      description: "This event is triggered everytime the user adds a product to their cart."
    # Update complete

Note that you can also define the new event in a different file. In this case, we add it in the existing file to group together events that are used in the same context.

Define a new property price by opening the ~/tutorial-catalog/my-properties.yaml file and adding the following details under spec.properties:

version: rudder/v0.1
kind: properties
metadata:
  name: mypropertygroup
spec:
  properties:
    - id: product_sku
      display_name: "SKU"
      type: string
      description: "Product SKU"
    - id: category
      display_name: "Category"
      type: string
      description: "Product's category"
    # New property added here
    - id: price
      display_name: "Price"
      type: integer
      description: "Product's price"
    # Update complete

Add the newly-defined event and property in the tracking plan by updating the ~/tutorial-catalog/my-tracking-plan.yaml file by adding the new event under spec.rules, as shown:

version: rudder/0.1
kind: tp
metadata:
  name: mytrackingplan
spec:
  id: mytrackingplan
  display_name: "Product Tracking Plan"
  description: "Contains all the events and properties for the Product Tracking Plan."
  rules:
   - type: event_rule
      id: product_viewed_rule
      event:
        $ref: "#/events/myeventgroup/product_viewed"
      allow_unplanned: false
      properties:
        - $ref: "#/properties/mypropertygroup/product_sku"
          required: true
        - $ref: "#/properties/mypropertygroup/category"
          required: false
    # New event rule added here
    - type: event_rule
      id: added_to_cart_rule
      event:
          $ref: "#/events/myeventgroup/added_to_cart"
      properties:
        - $ref: "#/properties/mypropertygroup/product_sku"
          required: true
        - $ref: "#/properties/mypropertygroup/price"
          required: true

As described in Step 6: Deploy data catalog resources, review the changes and apply them to your workspace by running the below commands:

rudder-cli tp apply -l ~/tutorial-catalog --dry-run

rudder-cli tp apply -l ~/tutorial-catalog

You can also run the below command to deploy the tracking plan changes to your workspace directly and skip any confirmation:

rudder-cli tp apply -l ~/tutorial-catalog --confirm=false

The output of this command should look like:

New resources:
  - event:added_to_cart
  - property:price

Updated resources:
  - tracking_plan:mytrackingplan
    - events: [map[allowUnplanned:false description:This event is triggered everytime a user views a product identitySection: localId:product_viewed name:Product Viewed properties:[map[config:<nil> description:Product SKU localId:product_sku name:SKU required:true type:string] map[config:<nil> description:Product's category localId:category name:Category required:false type:string]] type:track]] => [map[allowUnplanned:false description:This event is triggered everytime a user views a product identitySection: localId:product_viewed name:Product Viewed properties:[map[config:map[] description:Product SKU localId:product_sku name:SKU required:true type:string] map[config:map[] description:Product's category localId:category name:Category required:false type:string]] type:track] map[allowUnplanned:false description:This event is triggered everytime a product is added to cart identitySection: localId:added_to_cart name:Added to Cart properties:[map[config:map[] description:Product SKU localId:product_sku name:SKU required:true type:string] map[config:map[] description:Product's price localId:price name:Price required:true type:integer]] type:track]]

✔ Create event:added_to_cart
✔ Create property:price
✔ Update tracking_plan:mytrackingplan

The above output informs that a new event and property along with a change in the tracking plan is detected. It also informs that the new resources are created and the update operation is completed successfully.

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack