/rudder-import-and-evolve

name: rudder-import-and-evolve
description: Imports existing RudderStack workspace resources into YAML files for git-based management. Use when importing existing RudderStack resources to CLI management and evolving them safely
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

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

This prompts for an access token; the token decides the workspace. An agent does not run it: it asks the user to export `RUDDERSTACK_ACCESS_TOKEN` in the shell that starts the agent, and never asks the user to paste a token into the chat. See `rudder-cli-setup`.

Step 2: Verify Connection

rudder-cli workspace info --json

Should show your workspace `name` and `workspaceID`.

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)

The examples there end with `rudder-cli apply -l ./`, which waits on a confirmation prompt. An agent shows the user the `rudder-cli apply --dry-run -l ./` output first and waits for an explicit yes. Only then does it run `rudder-cli apply --confirm=false -l ./`, which applies with no prompt. Without `--confirm=false`, a non-interactive run auto-declines the prompt and applies nothing.

The CLI applies to the workspace of its token, not to the workspace a directory was imported from. The dry run names that workspace only from rudder-cli 0.28.0, on a first line `Workspace: <name> (<id>)`. In the multi-workspace examples, run `rudder-cli workspace info --json` before each dry run and check that `workspaceID` is that directory's workspace. Get that ID from the user, or from the `workspace info --json` output recorded when the directory was imported. Never take it from the `workspace_id` in a spec's `metadata.import`, because a spec copied from another directory carries that workspace's ID. If the IDs differ, stop. Changing the CLI's workspace means restarting the agent: the user exports that workspace's token as `RUDDERSTACK_ACCESS_TOKEN` and starts the agent again from that shell.

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, only after the user says yes to the dry run
rudder-cli apply --confirm=false -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:

# The dry run lists the deleted files' resources under "Removed resources:".
# Show it to the user and wait for an explicit yes.
rudder-cli apply --dry-run -l ./

# This will DELETE those resources