# Update Tracking Plans using Rudder CLI

This guide shows you how to update existing Tracking Plans in your Data Catalog using Rudder CLI.

## Prerequisites

Before updating a Tracking Plan, ensure you have:

1. [Rudder CLI tool]({{< ref "dev-tools/rudder-cli/" >}}) installed and [authenticated]({{< ref "dev-tools/rudder-cli/data-governance-walkthrough.md#1-authenticate-the-cli-tool" >}})
2. An existing Tracking Plan in your workspace
3. [Events]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/data-catalog/events.md" >}}) and [properties]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/data-catalog/properties.md" >}}) defined in your [Data Catalog project]({{< ref "dev-tools/rudder-cli/project-setup.md" >}})
4. Optional [custom types]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/data-catalog/custom-types.md" >}}) for validation

## Update tracking plans

You can update your Tracking Plans by modifying the YAML files in your Data Catalog project. These updates can include:

- Adding new events and properties
- Modifying validation rules
- Removing obsolete tracking

### Add new events

Add new events to your Tracking Plan by including additional event rules:

```yaml
version: rudder/v1
kind: tracking-plan
metadata:
  name: mytrackingplan
spec:
  id: mytrackingplan
  display_name: "Product Tracking Plan"
  description: "Contains all the events and properties for the Product Tracking Plan"
  rules:
    # Existing rules remain unchanged
    - type: event_rule
      id: product_viewed_rule
      event: "#event:product_viewed"
      properties:
        - property: "#property:product_sku"
          required: true

    # New event rule added
    - type: event_rule
      id: add_to_cart_rule
      event: "#event:add_to_cart"
      properties:
        - property: "#property:product_sku"
          required: true
        - property: "#property:quantity"
          required: true
```

### Modify properties

Update property requirements or add new properties to existing events:

```yaml
rules:
  - type: event_rule
    id: product_viewed_rule
    event: "#event:product_viewed"
    properties:
      # Existing properties
      - property: "#property:product_sku"
        required: true
      # New properties added
      - property: "#property:category"
        required: false
      # Modified requirement
      - property: "#property:price"
        required: true  # Changed from false
```

{{< info >}}
You can also remove events or properties by deleting their entries from the YAML file.
{{< /info >}}

## Example updates

The following examples show how to update Tracking Plans for different scenarios:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Ecommerce" %}}
```yaml
version: rudder/v1
kind: tracking-plan
metadata:
  name: ecommerce_tracking
spec:
  id: ecommerce_tracking
  display_name: "Ecommerce Tracking"
  description: "Updated Tracking Plan for ecommerce events"
  rules:
    # Existing product view tracking
    - type: event_rule
      id: product_viewed_rule
      event: "#event:product_viewed"
      properties:
        - property: "#property:sku"
          required: true
        - property: "#property:category"
          required: false
      # name and price are removed from the properties

    # New wishlist tracking
    - type: event_rule
      id: wishlist_add_rule
      event: "#event:wishlist_add"
      properties:
        - property: "#property:product_sku"
          required: true
        - property: "#property:list_id"
          required: true
```
{{% /tab %}}
{{% tab tabName="Authentication" %}}
```yaml
version: rudder/v1
kind: tracking-plan
metadata:
  name: user_auth_tracking
spec:
  id: user_auth_tracking
  display_name: "User Authentication Tracking"
  description: "Updated Tracking Plan for user authentication events"
  rules:
    - type: event_rule
      id: user_registered_rule
      event: "#event:user_registered"
      properties:
        - property: "#property:email"
          required: true
        - property: "#property:signup_method"
          required: true
          # referral_source is updated to required
        - property: "#property:referral_source"
          required: true # Changed from false
```
{{% /tab %}}
{{< /tabs >}}

## Validate and deploy updates

Before deploying your Tracking Plan updates, validate them to ensure they follow the correct structure and meet your requirements.

### Validate updates

Run the following command to validate your Tracking Plan updates:

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

The command checks your Tracking Plan updates for:

- Required fields and correct structure
- Valid event and property references
- Unique identifiers across your catalog
- Proper YAML syntax

If validation succeeds, the command returns no output. If it finds any issues, it displays specific error messages to help you fix them.

### Deploy updates

After validating your updates, deploy them to your RudderStack workspace:

1. Review the changes before deploying:
```shell
rudder-cli apply -l ~/tutorial-catalog --dry-run
```

2. Deploy the validated updates:

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

The above command:

- Updates existing Tracking Plans in your workspace
- Reports the status of each operation
- Requires confirmation before making changes (unless you use `--confirm=false`)

{{< info >}}
See the [End-to-end Walkthrough]({{< ref "dev-tools/rudder-cli/data-governance-walkthrough.md" >}}) for steps on validating and deploying Tracking Plan updates along with other Data Catalog resources.
{{< /info >}}

## Best practices

Follow these best practices when updating Tracking Plans:

- **Change management**
   - Review with stakeholders
   - Test thoroughly
   - Deploy gradually

- **Backward compatibility**
   - Consider existing implementations
   - Plan deprecation periods
   - Communicate changes

- **Testing**
   - Validate all changes
   - Test integrations
   - Monitor implementation

## Next steps

- Set up [GitHub Actions]({{< ref "dev-tools/rudder-cli/github-actions/_index.md" >}}) for automated Tracking Plan management

<br />