Terminal
Terminal/Skill
Imports an existing RudderStack workspace into YAML files kept in git, and explains how to change them without breaking live SDKs.
By RudderStack
Works with
npx skills add rudderlabs/rudder-agent-skills --skill rudder-import-and-evolveThis skill teaches how to import existing RudderStack resources into CLI management and safely evolve your tracking schema over time.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ RudderStack │────▶│ Import to │────▶│ Local YAML │
│ Workspace │ │ Local Files │ │ Files │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Git Version │
│ Control │
└─────────────────┘
rudder-cli auth login
Select your workspace when prompted.
rudder-cli workspace info
Should show your workspace name and ID.
rudder-cli import workspace
This imports:
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.
See references/evolution-patterns.md for detailed patterns including:
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 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
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
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.
# 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 ./
When importing resources from RudderStack workspace:
metadata.import.id values are legitimate workspace resourcesBefore applying changes:
rudder-cli validate -l ./ - no errorsrudder-cli apply --dry-run -l ./ - reviewed all changes