RudderTyper v2 Command Reference Beta

This page serves as a detailed reference for the RudderTyper v2 CLI commands available through Rudder CLI.

Overview

RudderTyper v2 is integrated into Rudder CLI and provides the following commands to generate type-safe client bindings from your Tracking Plans:

These are the only two typer subcommands. Code generation is configured entirely through flags — there is no typer init command and no ruddertyper.yml configuration file. Those belong to the npm-based RudderTyper v1, which is a separate tool.

List Tracking Plans

The workspace tracking-plans list command displays an interactive table with all available Tracking Plans in your workspace.

Command syntax

rudder-cli workspace tracking-plans list

Description

This command displays an interactive interface showing all Tracking Plans in your workspace.

Selecting a Tracking Plan from the list shows its details in a panel on the right, including the plan’s name, description, and current version, as shown:

Generate bindings

The typer generate command generates type-safe bindings for a specified platform from a Tracking Plan.

Command syntax

# From a Tracking Plan in your workspace
rudder-cli typer generate --platform=<PLATFORM> --tracking-plan-id=<TRACKING_PLAN_ID> [options]

# From Tracking Plan specs on disk
rudder-cli typer generate --local --location=<PROJECT_PATH> --platform=<PLATFORM> [options]

Parameters

Examples

• Generate TypeScript bindings with default settings:

rudder-cli typer generate --platform=typescript --tracking-plan-id=tp_1234567890abcdef

• Generate Kotlin bindings with default settings:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef

• Generate Swift bindings with default settings:

rudder-cli typer generate --platform=swift --tracking-plan-id=tp_1234567890abcdef

• Generate bindings to a specific output directory:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef -o ./generated-code

• Generate Kotlin bindings with a custom package name:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef --option packageName=com.example.package

Generate from local specs

--local reads your Data Catalog and Tracking Plan from YAML files on disk rather than fetching the plan from your workspace. No access token, network call, or rudder-cli apply is needed, and nothing is published when you generate.

Requirements

• Rudder CLI v0.25.0 or later.
• A local project directory containing data-catalog/ and tracking-plans/ specs.

Examples

• Generate TypeScript bindings from a project directory:

rudder-cli typer generate --local --location ./my-project --platform=typescript

• Generate from a project containing multiple Tracking Plans:

rudder-cli typer generate --local --location ./my-project \
    --tracking-plan-id storefront --platform=typescript

• Generate Kotlin bindings into a source tree with a custom package:

rudder-cli typer generate --local --location ./my-project \
    --platform=kotlin --output ./app/src/main/java/analytics \
    --option packageName=com.example.analytics

Behavior notes

• The generated output is identical to the remote flow for the same Tracking Plan.
• Resource kinds that code generation does not own — such as data-graphs/ and transformations/ — are skipped rather than failing the load, so they can sit alongside your catalog in the same project. rudder-cli apply still loads and validates every kind. Skipping was added in v0.21.0.

For the full workflow, including how to keep the generated client in step with the specs that produced it, see Generate Bindings from Local Specs and Instrumentation Workflow.

View platform options

The typer options command displays available platform-specific options for customizing generated code.

Command syntax

rudder-cli typer options --platform=<platform>

Parameters

Description

This command displays an interactive interface showing all available options for the specified platform, along with their descriptions and usage examples.

Example

rudder-cli typer options --platform=kotlin

Platform options

Platform-specific options customize how code is generated for each platform. Pass these options to the typer generate command using the --option flag with a key/value pair format: --option key=value.

TypeScript platform options

Examples

Generate TypeScript bindings with a custom output file name:

rudder-cli typer generate --platform=typescript --tracking-plan-id=tp_1234567890abcdef --option outputFileName=Events.ts

Kotlin platform options

Enabling composeImmutable causes the generated file to import androidx.compose.runtime.Immutable. Your module must have androidx.compose.runtime on its classpath, otherwise the file won’t compile. Any module that already uses Jetpack Compose has this dependency. If you enable this flag in a non-Compose module, the build fails with an unresolved reference.

Package name rules

The package name:

• Must be in lower case (regex: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$)
• Can contain lower case letters, digits, and underscores
• Segments must be separated by dots — each segment must start with a letter
• Cannot start or end with a dot
• Cannot have consecutive dots

Examples

Generate Kotlin bindings with a custom package name:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef --option packageName=com.example.package

Generate Kotlin bindings with a custom output file name:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef --option outputFileName=MyEvents.kt

Generate Kotlin bindings with Compose @Immutable annotations:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef --option composeImmutable=true

Combine multiple options:

rudder-cli typer generate --platform=kotlin --tracking-plan-id=tp_1234567890abcdef --option packageName=com.example.analytics --option outputFileName=Analytics.kt --option composeImmutable=true

Swift platform options

Examples

Generate Swift bindings with a custom output file name:

rudder-cli typer generate --platform=swift --tracking-plan-id=tp_1234567890abcdef --option outputFileName=Events.swift

Supported platforms

Generated code structure

The generated code structure depends on the platform and options specified.

TypeScript

TypeScript bindings are generated as a single RudderTyper.ts file. The file is organized into the following sections:

RudderTyper.ts
├── Property Enums      (union type aliases for enum-constrained properties)
├── Custom Types        (type aliases and interfaces for custom types)
├── Variant Types       (discriminated unions for multi-type rules)
├── Nested Object Types (interfaces for nested object properties)
├── Event Types         (interfaces for event properties and traits)
└── RudderTyper         (wrapper class with type-safe event methods)

The generated file imports its types from @rudderstack/analytics-js.

Kotlin

By default, Kotlin bindings are generated with the package name com.rudderstack.ruddertyper. The generated files should be placed in a directory structure that matches the package name:

src/main/kotlin/com/rudderstack/ruddertyper/

Custom package structure

If you specify a custom packageName option, place the generated files in a directory structure that matches your custom package name. For example, with packageName=com.example.package:

src/main/kotlin/com/example/package/

Swift

Swift bindings are generated as a single RudderTyper.swift file. The file is organized into the following sections:

RudderTyper.swift
├── Custom Types        (type aliases and structs for custom types)
├── Property Types      (type aliases for property types)
├── Event Properties    (structs for event properties and traits)
└── RudderTyperAnalytics (wrapper class with type-safe event methods)

The generated file imports Foundation and RudderStackAnalytics.

Using generated code

After generating the code, import it into your project and use the type-safe methods for tracking.

import { RudderTyper } from "./RudderTyper";

const typer = new RudderTyper(analytics);

typer.trackUserLogin({
  // ... properties defined in your Tracking Plan
})

import com.rudderstack.ruddertyper.RudderAnalytics

val typer = com.rudderstack.ruddertyper.RudderAnalytics(analytics)

typer.trackUserLogin(
  properties = TrackUserLoginProperties(
    // ... properties defined in your Tracking Plan
  )
)

import RudderStackAnalytics

let rudderTyper = RudderTyperAnalytics(analytics: analytics)

rudderTyper.trackUserLogin(
    properties: TrackUserLoginProperties(
        // ... properties defined in your Tracking Plan
    )
)

The generated code provides:

• Type-safe event methods: Each event in your Tracking Plan becomes a method
• Required parameters: Required properties are enforced at compile time
• Property validation: Property types match your Tracking Plan schema

See the RudderTyper v2 Walkthrough Guide for a complete setup example including SDK initialization.

Type mappings

RudderTyper maps YAML types from your Tracking Plan definitions to native types for each platform.

Properties that support multiple types are represented as a union type in TypeScript (for example, string | number), a sealed class in Kotlin, or an enum with associated values in Swift. For Kotlin and Swift, each type variant is represented as a distinct case, and a value property provides access to the underlying value.

Naming conventions

RudderTyper applies consistent naming conventions when generating code from your Tracking Plan definitions. The mobile platforms (Kotlin and Swift) share the same conventions, while TypeScript differs in a few places (noted below).

Event methods

TypeScript targets the web-based JavaScript SDK, so it exposes a page method instead of screen.

Properties and traits types

Type name prefixes

Event names are converted to CamelCase for method and type names, with the original event name preserved in the underlying SDK call.

Property names

Property names follow the same principle as event names. The generated identifier is idiomatic for the language, while the key sent to RudderStack is your Tracking Plan’s property name, unchanged.

For a Tracking Plan that defines product_id and first_name, the generated TypeScript interface uses camelCase fields:

export interface OrderCompleted {
  productId: string;
  profile: CustomTypeUserProfile;
}

You write camelCase at the call site:

typer.trackOrderCompleted({
  productId: "sku-1024",
  profile: { firstName: "Ada" },
});

And the event that reaches RudderStack uses your Tracking Plan’s names:

{
  "event": "Order Completed",
  "properties": {
    "product_id": "sku-1024",
    "profile": { "first_name": "Ada" }
  }
}

This holds at every level of the payload, including nested objects, arrays of objects, and properties typed as a custom type with variants.

The keys on the wire always match your Tracking Plan. Your events validate against the plan, your warehouse column names stay stable, and identity stitching keys behave as defined. You never need to rename keys yourself before calling the SDK.

RudderTyper first normalizes property names that aren’t valid identifiers in the target language:

• Separators such as dashes and spaces become word boundaries, so it emits user-id and first name as userId and firstName.
• If a name is still not a valid identifier after normalization, for example 用户名, RudderTyper preserves it verbatim and emits it as a quoted field.

In both cases, the key sent to RudderStack is your Tracking Plan’s property name, unchanged.

Supported event types

RudderTyper generates type-safe methods for the following event types:

Every generated method includes an optional options parameter that lets you pass additional configuration (such as integration overrides) to the underlying SDK call. RudderTyper automatically injects a ruddertyper context object into every call for attribution.

See more

• RudderTyper v2 Overview: Features and limitations of RudderTyper v2
• RudderTyper v2 Walkthrough: Step-by-step tutorial to get started with RudderTyper v2
• RudderTyper v1 (npm): npm-based code generation for JavaScript, TypeScript, Java, and Objective-C
• Tracking Plans: Create and manage Tracking Plans in RudderStack
• Commands Reference: All Rudder CLI commands