# RudderTyper v2 Command Reference


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:

| Command | Use case |
| :---- | :---- |
| `workspace tracking-plans list` | List all Tracking Plans in your workspace |
| `typer generate` | Generate type-safe client bindings from a Tracking Plan |
| `typer options` | View available platform-specific options for customizing generated code |

## List Tracking Plans

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

### Command syntax

```bash
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:

{{< image src="images/dev-tools/ruddertyper-v2/quickstart-1.webp" alt="List of Tracking Plans in your workspace" >}}

## Generate bindings

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

### Command syntax

```bash
rudder-cli typer generate --platform=<PLATFORM> --tracking-plan-id=<TRACKING_PLAN_ID> [options]
```

### Parameters

| Parameter | Type | <div style="width:350px">Description</div> |
| :----| :-----| :------|
| `--platform` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Specifies the platform for code generation. Supported values: `typescript`, `kotlin`, `swift`. |
| `--tracking-plan-id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Specifies the ID of the Tracking Plan to generate bindings from. You can obtain this ID using the [List Tracking Plans](#list-tracking-plans) command or from your RudderStack dashboard URL: `https://app.rudderstack.com/trackingPlans/<ID>`. |
| `-o`, `--output` | String | Specifies the output directory for storing generated files. If omitted, defaults to the current working directory. |
| `--option` | String | Specifies platform-specific options to customize the generated code. Accepts key/value pairs separated by `=`. You can specify multiple options by repeating the flag — see [Platform options](#platform-options) for available options. |
| `-h`, `--help` | Flag | Displays help information for the command. |

### Examples

- Generate TypeScript bindings with default settings:

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

- Generate Kotlin bindings with default settings:

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

- Generate Swift bindings with default settings:

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

- Generate bindings to a specific output directory:

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

- Generate Kotlin bindings with a custom package name:

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

## View platform options

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

### Command syntax

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

### Parameters

| Parameter | Type | Description |
| :----| :-----| :------|
| `--platform` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Specifies the platform to view options for. Supported values: `typescript`, `kotlin`, `swift`. |
| `-h`, `--help` | Flag | Displays help information for the command. |

### Description

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

{{< image src="images/dev-tools/ruddertyper-v2/quickstart-2.webp" alt="Rudder CLI Kotlin platform options" >}}

### Example

```bash
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

| Option | Type | Default | Description | Example |
| :----| :-----| :------| :------| :------|
| `outputFileName` | String | `RudderTyper.ts` | Name of the generated TypeScript file. | `--option outputFileName=Events.ts` |

#### Examples

Generate TypeScript bindings with a custom output file name:

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

### Kotlin platform options

| Option | Type | Default | Description | Example |
| :----| :-----| :------| :------| :------|
| `packageName` | String | `com.rudderstack.ruddertyper` | Package name for the generated Kotlin code. See [Package name rules](#package-name-rules) for more information. | `--option packageName=com.example.package` |
| `outputFileName` | String | `Main.kt` | Name of the generated Kotlin file. | `--option outputFileName=MyEvents.kt` |
| `composeImmutable` | Boolean | `false` | Annotates every generated `data class` with `@androidx.compose.runtime.Immutable` and adds the corresponding import. Useful if you use the generated types directly in Jetpack Compose UI trees — the annotation lets the Compose compiler skip recomposition when instances are structurally equal. | `--option composeImmutable=true` |

{{< warning >}}
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.
{{< /warning >}}

#### 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:

```bash
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:

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

Generate Kotlin bindings with Compose `@Immutable` annotations:

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

Combine multiple options:

```bash
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

The Swift platform does not currently expose any platform-specific options.

## Supported platforms

| Platform | Language | Use case |
|----------|----------|----------|
| `typescript` | TypeScript | Web applications using the JavaScript SDK |
| `kotlin` | Kotlin | Android and JVM applications |
| `swift` | Swift | iOS applications |

## 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:

```text
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:

```text
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`:

```text
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:

```text
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.

{{< tabs tabTotal="3" >}}
{{% tab tabName="TypeScript" %}}
```typescript
import { RudderTyper } from "./RudderTyper";

const typer = new RudderTyper(analytics);

typer.trackUserLogin({
  // ... properties defined in your Tracking Plan
})
```
{{% /tab %}}
{{% tab tabName="Kotlin" %}}
```kotlin
import com.rudderstack.ruddertyper.RudderAnalytics

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

typer.trackUserLogin(
  properties = TrackUserLoginProperties(
    // ... properties defined in your Tracking Plan
  )
)
```
{{% /tab %}}
{{% tab tabName="Swift" %}}
```swift
import RudderStackAnalytics

let rudderTyper = RudderTyperAnalytics(analytics: analytics)

rudderTyper.trackUserLogin(
    properties: TrackUserLoginProperties(
        // ... properties defined in your Tracking Plan
    )
)
```
{{% /tab %}}
{{< /tabs >}}

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]({{< ref "dev-tools/rudder-cli/ruddertyper-v2-walkthrough.md#6-instrument-your-application" >}}) 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.

{{< tabs tabTotal="3" >}}
{{% tab tabName="TypeScript" %}}
| YAML type | TypeScript type |
|-----------|-----------------|
| `string` | `string` |
| `integer` | `number` |
| `number` | `number` |
| `boolean` | `boolean` |
| `array` | `unknown[]` or `T[]` |
| `object` | `Record<string, unknown>` |
| `null` | `null` |
{{% /tab %}}
{{% tab tabName="Kotlin" %}}
| YAML type | Kotlin type |
|-----------|-------------|
| `string` | `String` |
| `integer` | `Long` |
| `number` | `Double` |
| `boolean` | `Boolean` |
| `array` | `JsonArray` or `List<T>` |
| `object` | `JsonObject` |
| `null` | `JsonNull` |
{{% /tab %}}
{{% tab tabName="Swift" %}}
| YAML type | Swift type |
|-----------|------------|
| `string` | `String` |
| `integer` | `Int` |
| `number` | `Double` |
| `boolean` | `Bool` |
| `array` | `[Any]` or `[T]` |
| `object` | `[String: Any]` |
| `null` | `NSNull` |
{{% /tab %}}
{{< /tabs >}}

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

| Event type | Kotlin / Swift | TypeScript | Example |
|------------|----------------|------------|---------|
| `track` | `track{EventName}` | `track{EventName}` | `trackUserSignedUp` |
| `identify` | `identify` | `identify` | `identify` |
| `screen` (mobile) / `page` (web) | `screen{EventName}` | `page` | `screenProductViewed` (Kotlin/Swift), `page` (TypeScript) |
| `group` | `group` | `group` | `group` |

{{< info >}}
TypeScript targets the web-based [JavaScript SDK]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/" >}}), so it exposes a `page` method instead of `screen`.
{{< /info >}}

### Properties and traits types

| Event type | Kotlin / Swift struct | TypeScript type | Example (TypeScript) |
|------------|-----------------------|-----------------|----------------------|
| `track` | `Track{EventName}Properties` | `{EventName}` interface | `UserSignedUp` |
| `identify` | `Identify{EventName}Traits` | `IdentifyTraits` interface | `IdentifyTraits` |
| `screen` / `page` | `Screen{EventName}Properties` | `PageProperties` interface | `PageProperties` |
| `group` | `Group{EventName}Traits` | `GroupTraits` interface | `GroupTraits` |

### Type name prefixes

| Source | Prefix | Example |
|--------|--------|---------|
| Property | `Property` | `PropertySomeString` |
| Custom type | `CustomType` | `CustomTypeSomeStringType` |

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.

| Platform | Generated identifier | Key on the wire |
|----------|----------------------|-----------------|
| TypeScript | camelCase | Tracking Plan property name |
| Kotlin | camelCase | Tracking Plan property name |
| Swift | camelCase | Tracking Plan property name |

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

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

You write camelCase at the call site:

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

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

```json
{
  "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.

{{< success >}}
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.
{{< /success >}}

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:

| Event type | Method signature | Notes |
|------------|-----------------|-------|
| `track` | `track{EventName}(properties:options:)` | Properties type with typed fields |
| `identify` | `identify(userId:traits:options:)` | Traits type with typed fields |
| `screen` / `page` | `screen{EventName}(properties:category:options:)` | Properties type with typed fields; `category` is optional. On TypeScript (web), this is exposed as `page` |
| `group` | `group(groupId:traits:options:)` | Traits type with typed fields |

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]({{< ref "dev-tools/rudder-cli/ruddertyper-v2.md" >}}): Features and limitations of RudderTyper v2
- [RudderTyper v2 Walkthrough]({{< ref "dev-tools/rudder-cli/ruddertyper-v2-walkthrough.md" >}}): Step-by-step tutorial to get started with RudderTyper v2
- [RudderTyper v1 (npm)]({{< ref "dev-tools/ruddertyper.md" >}}): npm-based code generation for JavaScript, TypeScript, Java, and Objective-C
- [Tracking Plans]({{< ref "data-governance/tracking-plans/" >}}): Create and manage Tracking Plans in RudderStack
- [Commands Reference]({{< ref "dev-tools/rudder-cli/commands.md" >}}): All Rudder CLI commands