Select spec version:

Generate Bindings from a Snapshot

Save a Tracking Plan to a file, then generate type-safe client bindings from it on any machine, without an access token or an API call.
Available Plans
  • free
  • growth
  • enterprise

By default, rudder-cli typer generate fetches a Tracking Plan from your RudderStack workspace, which requires an access token and API calls on every run.

A snapshot splits that into two steps. typer snapshot saves a Tracking Plan to a file where you have credentials. typer generate --snapshot then reads that file wherever you build, with no access token and no API call.

When to use a snapshot

Use a snapshot when:

  • Your build machines don’t have credentials. A Gradle build or a developer laptop can generate the bindings without a RudderStack token.
  • You want repeatable builds. A snapshot changes only when you run typer snapshot again, so edits to the plan in your workspace don’t change a build.
  • You want to build against a specific Tracking Plan version. Save that version, and the build keeps using it until you choose to move.
  • Generation from your workspace is slow. Reading a file makes no API calls, so generation finishes in seconds.

Use --local instead when you author the Tracking Plan YAML yourself and have it in the repository. Use a snapshot when the plan exists only in your workspace.

Prerequisites

  • Install Rudder CLI v1.1.0 or later. Verify with rudder-cli --version.
  • An access token for the machine that saves the snapshot. The machine that generates the bindings doesn’t need one.

Save a snapshot

Run typer snapshot with the ID of your Tracking Plan:

bash
rudder-cli typer snapshot --tracking-plan-id tp_1234567890abcdef -o tracking-plan.snapshot.json

The command prints the Tracking Plan name, its version, and the number of events it saved.

The file holds the Tracking Plan with its event schemas, plus a formatVersion. It includes the workspace and user IDs that the API returns, and no credentials, so you can decide where to store it.

Generate the bindings

Pass the file to typer generate with --snapshot:

bash
rudder-cli typer generate \
    --snapshot ./tracking-plan.snapshot.json \
    --platform kotlin \
    --output ./generated \
    --option packageName=com.example.analytics
Don’t pass --tracking-plan-id, --tracking-plan-version, or --local with --snapshot. A snapshot holds exactly one Tracking Plan at one version, so the CLI returns an error instead of generating from a plan you didn’t name.

Every other flag, --platform, --output, and --option, works as it does when you generate from your workspace.

The CLI sends one telemetry event when typer generate finishes, including with --snapshot. Set RUDDERSTACK_CLI_TELEMETRY_DISABLED=true to turn telemetry off. The Gradle task below sets it for that reason.

Pin a Tracking Plan version

Without a version, typer snapshot saves the latest version of the plan. To save an earlier one, add --tracking-plan-version:

bash
rudder-cli typer snapshot --tracking-plan-id tp_1234567890abcdef --tracking-plan-version 3 -o tracking-plan.snapshot.json

The flag also works with typer generate when you generate from your workspace.

The rules and properties in the snapshot come from the version you pin. Event descriptions come from the current event records.

Use a snapshot in CI and in builds

The usual setup has two jobs in two places:

  1. A CI job that has credentials runs typer snapshot and publishes the file, for example to an artifact store.
  2. The build reads the file from the project directory and runs typer generate --snapshot. You can commit the file, or add a step that downloads it before the build.

A snapshot doesn’t expire. Save a new one when you want the build to pick up a plan change.

Generate during a Gradle build

This task runs the generation as part of a Kotlin JVM module’s build. Add it to build.gradle.kts:

kotlin
val rudderCli = providers.environmentVariable("RUDDER_CLI").orElse("rudder-cli")
val rudderCliVersion = providers.environmentVariable("RUDDER_CLI_VERSION").orElse("unpinned")
val snapshot = layout.projectDirectory.file("tracking-plan.snapshot.json")
val generatedDir = layout.buildDirectory.dir("generated/rudder/kotlin")

val generateRudderTyper by tasks.registering(Exec::class) {
    inputs.file(snapshot)
    inputs.property("rudderCli", rudderCli)
    inputs.property("rudderCliVersion", rudderCliVersion)
    outputs.dir(generatedDir)

    environment("RUDDERSTACK_CLI_TELEMETRY_DISABLED", "true")

    commandLine(
        rudderCli.get(), "typer", "generate",
        "--platform", "kotlin",
        "--snapshot", snapshot.asFile.absolutePath,
        "--output", generatedDir.get().asFile.absolutePath,
        "--option", "packageName=com.example.analytics",
    )
}

// A task provider as a source directory also makes compileKotlin depend on the task
kotlin.sourceSets.getByName("main").kotlin.srcDir(generateRudderTyper)

Gradle skips the task when the snapshot file, the CLI version, and the output directory are unchanged. The generated file’s header contains the CLI version and no timestamp, so repeated runs write identical files.

The task sets RUDDERSTACK_CLI_TELEMETRY_DISABLED=true, so a build machine without outbound access doesn’t wait on the telemetry request.

Gradle doesn’t look inside the executable that an Exec task runs, so the CLI version has to be a declared input. Set RUDDER_CLI_VERSION to the version you install, and an upgrade reruns the task. The install script accepts the same variable:

bash
export RUDDER_CLI_VERSION=<version>
curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/latest/download/install.sh | sh
This task is for a Kotlin JVM module. An Android module has one Kotlin compile task for each variant, such as compileDebugKotlin, and no task named compileKotlin. Adding the generated directory to an Android module needs the Android Gradle Plugin’s variant API, which this page doesn’t cover.

Troubleshooting

ErrorCause and fix
--local and --snapshot cannot be used togetherRemove --local. Pick one source for the Tracking Plan.
--tracking-plan-id does not apply with --snapshotRemove --tracking-plan-id. The snapshot already names its Tracking Plan.
--tracking-plan-version only applies when generating from the remote workspaceRemove --tracking-plan-version from typer generate --snapshot, and pin the version when you run typer snapshot.
<file> is not a snapshot this CLI can read: regenerate it with 'typer snapshot'The file is JSON but not a snapshot, for example a raw API response. Create it again with typer snapshot. A file that isn’t valid JSON returns decoding snapshot <file>: ... instead.
snapshot <file> has format version <N>, this CLI reads version <M>: upgrade rudder-cli to read itA newer CLI wrote the snapshot. Upgrade Rudder CLI.
snapshot <file> has no tracking plan: regenerate it with 'typer snapshot'The file is JSON with a supported formatVersion, but it has no Tracking Plan in it, for example because someone edited it by hand. Create it again with typer snapshot.
the server does not return events for a pinned tracking plan versionYour workspace’s RudderStack release doesn’t return events for a specific version yet. Save the latest version instead.
The CLI exits with an error about $HOME/.rudderThe CLI always writes its log to $HOME/.rudder/cli.log, even when you pass --config, and exits if it can’t create it. In a sandbox with a read-only home directory, run the command with HOME set to a writable directory.

See more

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.