# RudderTyper v2 Command Reference


> Complete RudderTyper v2 command reference for generating type-safe client bindings via Rudder CLI.



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, either from your workspace or from local specs |
| `typer options` | View available platform-specific options for customizing generated code |

**Info:** 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 [RudderTyper v1 Reference](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/v1/).

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

![List of Tracking Plans in your workspace](/docs/images/dev-tools/ruddertyper-v2/quickstart-1.webp)

## Generate bindings

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

### Command syntax

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

| Parameter | Type | <div>Description</div> |
| :----| :-----| :------|
| `--platform` <br/> Required | String | Specifies the platform for code generation. Supported values: `typescript`, `kotlin`, `swift`. |
| `--tracking-plan-id` | String | Specifies the Tracking Plan to generate bindings from. **Required** without `--local`: obtain the ID using the [List Tracking Plans](#list-tracking-plans) command or from your RudderStack dashboard URL `https://app.rudderstack.com/trackingPlans/<ID>`. With `--local`, this is the `spec.id` in your local Tracking Plan YAML, and it is optional when the project contains exactly one Tracking Plan. |
| `--local` | Flag | Generates from Tracking Plan specs on disk instead of your workspace — no authentication, network call, or `rudder-cli apply` required. Generally available from Rudder CLI v0.25.0; on v0.24.0 and earlier it requires feature flags. See [Generate from local specs](#generate-from-local-specs). |
| `-l`, `--location` | String | Path to the project directory or spec file to read when `--local` is set. If omitted, defaults to the current working directory. Has no effect without `--local`. |
| `-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
```

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

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

- Generate from a project containing multiple Tracking Plans:

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

```bash
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](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-local-generation/) and [Instrumentation Workflow](https://www.rudderstack.com/docs/rudder-cli/instrumentation-workflow/).

## 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/> Required | 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.

![Rudder CLI Kotlin platform options](/docs/images/dev-tools/ruddertyper-v2/quickstart-2.webp)

### 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&#39;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:

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

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

#### Examples

Generate Swift bindings with a custom output file name:

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

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

#### TypeScript

```typescript
import { RudderTyper } from "./RudderTyper";

const typer = new RudderTyper(analytics);

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

```kotlin
import com.rudderstack.ruddertyper.RudderAnalytics

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

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

```swift
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](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-walkthrough/#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.

#### TypeScript

| YAML type | TypeScript type |
| --- | --- |
| `string` | `string` |
| `integer` | `number` |
| `number` | `number` |
| `boolean` | `boolean` |
| `array` | `unknown[]` or `T[]` |
| `object` | `Record&lt;string, unknown&gt;` |
| `null` | `null` |
#### Kotlin

| YAML type | Kotlin type |
| --- | --- |
| `string` | `String` |
| `integer` | `Long` |
| `number` | `Double` |
| `boolean` | `Boolean` |
| `array` | `JsonArray` or `List&lt;T&gt;` |
| `object` | `JsonObject` |
| `null` | `JsonNull` |
#### Swift

| YAML type | Swift type |
| --- | --- |
| `string` | `String` |
| `integer` | `Int` |
| `number` | `Double` |
| `boolean` | `Bool` |
| `array` | `[Any]` or `[T]` |
| `object` | `[String: Any]` |
| `null` | `NSNull` |

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](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/), so it exposes a `page` method instead of `screen`.

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

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](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2/): Features and limitations of RudderTyper v2
- [RudderTyper v2 Walkthrough](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-walkthrough/): Step-by-step tutorial to get started with RudderTyper v2
- [RudderTyper v1 Reference](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/v1/): npm commands, modes, and `ruddertyper.yml`
- [Tracking Plans](https://www.rudderstack.com/docs/data-governance/tracking-plans/): Create and manage Tracking Plans in RudderStack
- [Commands Reference](https://www.rudderstack.com/docs/rudder-cli/commands/): All Rudder CLI commands