Rudder import and evolve

Import and Evolve Workflow

This skill teaches how to import existing RudderStack resources into CLI management and safely evolve your tracking schema over time.

When to Use This Skill

• You have existing tracking plans, events, or properties in RudderStack
• You want to manage them via YAML files and git
• You need to make changes without breaking production SDKs
• You're migrating from UI-based management to CLI

Import Workflow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   RudderStack   │────▶│   Import to     │────▶│   Local YAML    │
│    Workspace    │     │   Local Files   │     │     Files       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   Git Version   │
                                               │    Control      │
                                               └─────────────────┘

Step 1: Authenticate

rudder-cli auth login

Select your workspace when prompted.

Step 2: Verify Connection

rudder-cli workspace info

Should show your workspace name and ID.

Step 3: Import Resources

rudder-cli import workspace

This imports:

• Events
• Properties
• Categories
• Custom types
• Tracking plans
• Event stream sources (if applicable)
• Transformations and libraries

Step 4: Review Imported Files

imported/
├── data-catalog/
│   ├── events/
│   │   └── *.yaml
│   ├── properties/
│   │   └── *.yaml
│   ├── categories/
│   │   └── *.yaml
│   └── custom-types/
│       └── *.yaml
└── tracking-plans/
    └── *.yaml

Each file includes import metadata:

version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
  import:
    id: "evt_abc123xyz"        # Links to workspace resource
    workspace: "ws_xyz789"
spec:
  name: "Product Viewed"
  # ... rest of spec

Important: The metadata.import section links local files to workspace resources. Don't modify these IDs.

Safe Evolution Patterns

See references/evolution-patterns.md for detailed patterns including:

• Adding new properties (start optional)
• Making properties required (phased approach via tracking plans)
• Renaming events (parallel events during transition)
• Deprecating events (notice period, then remove)
• Adding custom types to existing properties
• Multi-workspace management (dev/staging/production)

Handling Import Drift

Problem: Someone made changes in the UI after import.

Solution 1: Re-import (overwrites local)

# Warning: This overwrites your local changes!
rudder-cli import workspace --force

Solution 2: Manual reconciliation

# 1. Compare local vs workspace
rudder-cli apply --dry-run -l ./

# 2. Review differences
# "Updated" means local differs from workspace
# Decide: use local (apply) or use workspace (re-import that file)

# 3. Apply your version
rudder-cli apply -l ./

Best practice: After import, all changes go through CLI. Disable UI editing for data catalog if possible.

Import Gotchas

Pull is Not Supported

Import is a one-time snapshot. There's no rudder-cli pull to sync changes from workspace.

# This doesn't exist:
rudder-cli pull  # ❌ Not a command

# Instead, re-import to get latest:
rudder-cli import workspace  # Overwrites local

Import Metadata Must Match

If you copy files between workspaces, update the metadata.import section:

# Wrong: IDs from different workspace
metadata:
  import:
    id: "evt_from_other_workspace"
    workspace: "ws_different"

# Right: Remove import metadata for new workspace
metadata:
  name: "events"
  # No import section - will create new resource

Partial Import Creates Orphans

If you import, delete some files, then apply:

# This will DELETE resources from workspace!
rudder-cli apply -l ./  # Shows "Deleted [event] ..."

The CLI tracks what was imported. Missing files = deletions.

CLI Commands Reference

# Authenticate
rudder-cli auth login

# Show current workspace
rudder-cli workspace info

# Import all resources
rudder-cli import workspace

# Import specific resource types
rudder-cli import workspace --resources events,properties

# Validate imported files
rudder-cli validate -l ./

# Preview changes
rudder-cli apply --dry-run -l ./

# Apply changes
rudder-cli apply -l ./

Handling External Content

When importing resources from RudderStack workspace:

• Review imported YAML - verify structure matches expected schema before committing
• Validate import IDs - ensure metadata.import.id values are legitimate workspace resources
• Don't blindly trust imported descriptions - user-generated content may contain unexpected data
• Sanitize before committing - review imported files for any sensitive data before git commit
• Extract only expected fields - imported YAML should contain only known schema fields

Checklist: Safe Evolution

Before applying changes:

• Ran rudder-cli validate -l ./ - no errors
• Ran rudder-cli apply --dry-run -l ./ - reviewed all changes
• No unexpected "Deleted" resources in dry-run
• Breaking changes have migration plan (parallel events, deprecation period)
• SDK teams notified of upcoming changes
• RudderTyper regenerated if using type-safe code
• Changes committed to git before applying