/rudder-transformations

name: rudder-transformations
description: Creates and manages RudderStack transformations and libraries with local testing. Use when creating, editing, or managing RudderStack transformations and transformation libraries using the Rudder CLI
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

RudderStack Transformations with Rudder CLI

Overview

RudderStack transformations allow real-time event manipulation using JavaScript or Python. Libraries provide reusable code shared across transformations. Both are managed as code using YAML specs and the Rudder CLI.

Recommended Workflow

Follow this loop for every change — authoring a new transformation or library, or editing existing code. Testing locally with fixtures is the key step that distinguishes transformations work from other CLI workflows.

digraph transformations_workflow {
    rankdir=TB;
    "rudder-cli workspace info --json" [shape=box];
    "Authenticated?" [shape=diamond];
    "User exports RUDDERSTACK_ACCESS_TOKEN" [shape=box];
    "Edit YAML / JS / fixtures" [shape=box];
    "rudder-cli validate -l ./" [shape=box];
    "Validation errors?" [shape=diamond];
    "Fix errors" [shape=box];
    "rudder-cli transformations test --all -l ./" [shape=box];
    "Tests pass?" [shape=diamond];
    "Fix code or expected output" [shape=box];
    "rudder-cli apply --dry-run -l ./" [shape=box];
    "Diff matches intent?" [shape=diamond];
    "Adjust specs" [shape=box];
    "rudder-cli apply --confirm=false -l ./" [shape=box];
    "Done" [shape=doublecircle];

    "rudder-cli workspace info --json" -> "Authenticated?";
    "Authenticated?" -> "User exports RUDDERSTACK_ACCESS_TOKEN" [label="no"];
    "User exports RUDDERSTACK_ACCESS_TOKEN" -> "rudder-cli workspace info --json";
    "Authenticated?" -> "Edit YAML / JS / fixtures" [label="yes"];
    "Edit YAML / JS / fixtures" -> "rudder-cli validate -l ./";
    "rudder-cli validate -l ./" -> "Validation errors?";
    "Validation errors?" -> "Fix errors" [label="yes"];
    "Fix errors" -> "rudder-cli validate -l ./";
    "Validation errors?" -> "rudder-cli transformations test --all -l ./" [label="no"];
    "rudder-cli transformations test --all -l ./" -> "Tests pass?";
    "Tests pass?" -> "Fix code or expected output" [label="no"];
    "Fix code or expected output" -> "rudder-cli validate -l ./";
    "Tests pass?" -> "rudder-cli apply --dry-run -l ./" [label="yes"];
    "rudder-cli apply --dry-run -l ./" -> "Diff matches intent?";
    "Diff matches intent?" -> "Adjust specs" [label="no"];
    "Adjust specs" -> "rudder-cli validate -l ./";
    "Diff matches intent?" -> "rudder-cli apply --confirm=false -l ./" [label="yes"];
    "rudder-cli apply --confirm=false -l ./" -> "Done";
}

**Steps:** 1. **Verify auth.** `rudder-cli workspace info --json`. If it fails, an agent asks the user to export `RUDDERSTACK_ACCESS_TOKEN` in the shell that starts the agent and restart it; it does not run `rudder-cli auth login` (a terminal prompt) and never asks the user to paste a token into the chat. A person at a terminal can run `rudder-cli auth login`. See `rudder-cli-setup`. 2. **Validate.** `rudder-cli validate -l ./` catches YAML schema errors, missing files, camelCase `import_name` violations. 3. **Test locally.** `rudder-cli transformations test --all -l ./` runs each transformation against its `tests/input/*.json` fixtures and diffs against `tests/output/*.json`. Use `--modified` for faster iteration or pass a specific transformation id. 4. **Dry run.** `rudder-cli apply --dry-run -l ./` shows the diff that would be applied. Check for unexpected deletions. 5. **Apply.** `rudder-cli apply --confirm=false -l ./` publishes libraries and transformations atomically (correct order handled by the CLI). It applies with no prompt, so an agent runs it only after showing the user the dry run and getting an explicit yes. Without `--confirm=false`, a non-interactive run (agent, CI) auto-declines the confirmation prompt and applies nothing.

For the broader validate → apply cycle that applies to all CLI-managed resources, see the `rudder-cli-workflow` skill. This skill specializes it with the local-test step.

Worked example

A complete end-to-end project — library, transformation, fixtures, and README — lives at `examples/transformations-workflow/` in this repo. It includes a ported Base64 library (`base64-lib`), a sample transformation that uses it, and input/output test fixtures. Use it as a scaffold for new transformations or as a reference for `tests/` structure.

Directory Structure

transformations/
  my-transformation.yaml         # Transformation spec
  my-library.yaml                # Library spec
  javascript/
    my-transformation.js         # JavaScript code
    my-library.js               # Library code
  python/
    my-transformation.py         # Python code
    my-library.py               # Library code
  tests/
    input/
      event1.json               # Test input events
    output/
      event1.json               # Expected outputs

YAML Schemas

Transformation Spec

version: "rudder/v1"
kind: "transformation"
metadata:
  name: "transformations"
  # Optional: import section for linking to existing workspace resources
  import:
    workspaces:
      - workspace_id: "your-workspace-id"
        resources:
          - remote_id: "existing-transformation-id"
            urn: "transformation:my-transformation"
spec:
  id: "my-transformation"           # Unique identifier (used as external ID)
  name: "My Transformation"         # Human-readable name
  description: "Description"        # Optional
  language: "javascript"            # "javascript" or "python"
  file: "javascript/my-transformation.js"  # Path to code (relative to YAML)
  # OR inline:
  # code: |
  #   export function transformEvent(event) { return event; }
  tests:                            # Optional - local testing only
    - name: "basic-test"
      input: "./tests/input"