Destination Type Reference for Rudder CLI

Every destination spec names a type, and that type decides which config keys the spec accepts. This section documents those keys, one page per destination type.

The rules on this page apply to every type. The per-type pages cover only what’s specific to that destination.

Destination support requires Rudder CLI v0.25.0 or later. Some types need a later version — see the Available since column in Supported destination types.

Upgrade if you’re using an earlier version.

Supported destination types

Use the type value in YAML. Every type below takes definition_version: 1. The Available since column in the below table shows the release that made each type available.

The type pages document the latest release. For what changed in each release since a type became available, including breaking changes, see Destination Type Changes by Release.

On Rudder CLI v0.29.0 or later, rudder-cli docs destination <type> prints a type’s keys, allowed values, defaults, secret keys, and connection modes as the release you run defines them. Add --json for JSON output.

Important considerations

• Rudder CLI rejects any type outside this table. You can define more destinations in the RudderStack dashboard than what you can define in Rudder CLI.
• To start from a destination you already configured in the dashboard, run rudder-cli import workspace — the imported YAML uses the same keys these pages document. See How to Import Workspace Resources for more information.

Config key rules

These rules hold for every destination type.

Keys are snake_case

Local YAML uses snake_case config keys. Rudder CLI converts them to the API’s camelCase at apply time. A camelCase key in the spec is treated as an unknown key.

Unknown keys fail validation

config accepts only the keys its type declares. Anything else fails rudder-cli validate with:

unknown config field "<key>"

A key that’s valid for one destination type isn’t valid for another. There are no shared optional extras beyond connection_mode and consent_management.

Keys from a later release

The type pages document the latest release, so a key on a page can be newer than the Rudder CLI release you run. An earlier release doesn’t know such a key:

• It rejects the key in a spec with unknown config field "<key>"
• It leaves the key out when it imports the destination
• An update it applies removes the key from the destination, even when the key was set in the RudderStack dashboard, because an update sends the destination’s whole config

Upgrade before you manage a destination that uses such a key. Destination Type Changes by Release lists what each release added and changed.

Omitting a key with a default is safe

Where a key declares a default, Rudder CLI fills that value in before it validates the spec and before the spec reaches the API, because the backend applies the same default when it stores the destination. Omitting such a key is equivalent to writing its default: it doesn’t produce a permanent diff on the next apply, and it’s validated as though you had written the default — which can make another key required.

A default inside a nested block, like Amplitude’s sdk_version.web, fills in only when the spec writes that block. Omit the whole block and nothing is sent for it.

Keys without a default are sent only when you set them.

Some keys can’t change after the first apply

A key marked immutable on a type page is fixed once the destination exists. The API rejects an update that changes it.

Rudder CLI doesn’t check immutability locally. validate accepts the change and apply sends it, so the failure surfaces at the API rather than in your pull request. To change an immutable key, create a new destination instead.

Some keys aren’t in the dashboard

A key marked internal on a type page isn’t surfaced by the RudderStack dashboard. Rudder CLI accepts it so that an existing value survives an update, and so that a spec you import round-trips unchanged. Set it only if you know your destination needs it.

Source types

A destination declares the source types it accepts events from. Each type page lists its own set, drawn from the tokens below.

A source’s own definition resolves to exactly one token. Note that cloud and cloud_source are different tokens: a webhook or server-side SDK source resolves to cloud, while a cloud app source resolves to cloud_source.

Connection modes

A connection mode describes how a given source type connecting to this destination instance routes its events:

Note that:

• The connection mode is a property of the source-destination pair, not of the source or the destination alone.
• Two destinations fed by the same source can run in different modes.
• A source type supported in device or hybrid mode by one destination may be cloud-only on another.

For more information, see RudderStack Connection Modes.

Where the mode is declared

connection_mode lives in the destination’s config block, keyed by local source type — not on the connection spec.

config:
  connection_mode:
    web: device
    android_kotlin: cloud

Naming a source type the destination doesn’t support fails validation, and so does a mode that source type doesn’t support on this destination.

An entry is required for every source type you connect. Without one, validate reports:

destination '<id>' config has no 'connection_mode' entry for source type '<source_type>'

After you upgrade to v0.28.0, check destinations that already have a Reverse ETL connection

If you imported a destination with Rudder CLI v0.27.0 or earlier, its spec can be missing the warehouse entries that the dashboard adds when you connect a Reverse ETL source. On v0.28.0 or later, Rudder CLI plans an update that removes those entries from the workspace destination, and apply strips them along with any warehouse consent settings.

This affects ActiveCampaign, Amazon S3, Amplitude, Attentive Tag, BigQuery Stream, Braze, Customer.io, Facebook Conversions, Facebook Pixel, Google Analytics 4, Google Cloud Storage, HubSpot, Iterable, Mixpanel, PostHog, TikTok Ads, and Webhook destinations.

After you upgrade and before your next apply, add the warehouse entry to connection_mode in the destination’s spec, and to consent_management if the workspace destination has consent settings for it. Then, run apply --dry-run and confirm that the plan no longer lists the destination as updated.

Consent management

consent_management is accepted by every destination type, keyed by local source type. Each source type maps to an array of consent entries.

config:
  consent_management:
    web:
      - provider: oneTrust
        consents:
          - analytics
          - marketing
    react_native:
      - provider: custom
        resolution_strategy: and
        consents:
          - analytics

Within one source type’s array, each provider can appear at most once. Only source types the destination supports are allowed.

Each consent string must be at most 100 characters, unless it’s written as a {{ path || fallback }} template, which is accepted at any length.

A plain value over the limit reports 'consent' must be at most 100 characters.

For the feature itself, see Consent Management in RudderStack.

Secrets

Each type page lists the keys Rudder CLI treats as secrets. Write each one you use as a {{ .VARIABLE_NAME }} reference rather than a literal, and supply the value from the environment, prefixed with RUDDER_, or from a var file:

export RUDDER_BRAZE_REST_API_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• validate substitutes variables too, so every variable a spec references must be set when you run it. An undefined one stops the run.
• validate warns when a secret key holds anything but one {{ .VAR }} reference with no default, and when one variable fills two secret keys. It masks secret values in the lines it prints.
• Rudder CLI substitutes each value into the YAML before parsing it. A value containing double quotes, such as a JSON key file, needs a single-quoted reference, '{{ .VAR }}', and a single quote in a value that fills one is written as ''. A multi-line value, like a PEM key, keeps its line breaks when it fills a quoted reference, in either quote style. In a var file, write it as a YAML literal block. The type pages show the form where a key needs it.
• rudder-cli import writes a secret only when the API returns its value, and the API doesn’t return every secret. A returned secret is written as a single-quoted reference named after the spec id and the key, upper-cased with - turned into _ — for example, app_key on a destination imported as braze-prod becomes '{{ .BRAZE_PROD_APP_KEY }}' — and listed in a secrets.vars.yaml file next to the imported specs for you to fill in. A secret the API doesn’t return, such as BigQuery’s credentials, is left out of the spec, so add it yourself before you apply.

See How to Use Variable Substitution in Rudder CLI.

See more

• Destination YAML Reference for the spec envelope — id, display_name, type, definition_version, enabled, transformation
• Manage Destinations using Rudder CLI for the feature overview
• End-to-End Walkthrough: Destinations with Rudder CLI for step-by-step setup
• Connection YAML Reference to link a destination to a source