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



By default, [`rudder-cli typer generate`](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/) 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`](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/#save-a-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`](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-local-generation/) 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](https://www.rudderstack.com/docs/rudder-cli/installation/) **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
```

**Info:** Don&#39;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&#39;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.

**Info:** 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](https://www.rudderstack.com/docs/rudder-cli/installation/) accepts the same variable:

```bash
export RUDDER_CLI_VERSION=<version>
curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/latest/download/install.sh | sh
```

**Info:** 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&#39;s variant API, which this page doesn&#39;t cover.

## Troubleshooting

| Error | Cause and fix |
| :---- | :---- |
| `--local and --snapshot cannot be used together` | Remove `--local`. Pick one source for the Tracking Plan. |
| `--tracking-plan-id does not apply with --snapshot` | Remove `--tracking-plan-id`. The snapshot already names its Tracking Plan. |
| `--tracking-plan-version only applies when generating from the remote workspace` | Remove `--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 it` | A 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 version` | Your 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/.rudder` | The 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

- [RudderTyper v2 Command Reference](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-command-reference/)
- [Generate Bindings from Local Specs](https://www.rudderstack.com/docs/rudder-cli/ruddertyper-v2-local-generation/)
- [Instrumentation Workflow](https://www.rudderstack.com/docs/rudder-cli/instrumentation-workflow/)

