How to Use Variable Substitution in Rudder CLI Beta

Keep destination and warehouse credentials out of the YAML you commit. Write {{ .VAR }} references in specs, store the values in a var file, and pass --var-file when you apply.

You can also substitute non-secret values (for example an account_id that differs across development and production).

Variable substitution is experimental.

Enable the enableVarSubstitution flag in your CLI configuration (or set RUDDERSTACK_X_ENABLE_VAR_SUBSTITUTION=true) before you apply specs that contain {{ .VAR }} references. Without it, Rudder CLI doesn’t resolve the placeholders.

Prerequisites

• Install Rudder CLI and authenticate against your workspace.
• Define or import YAML from the Destination YAML Reference or Account Resources YAML Reference that uses secret fields.

Enable variable substitution

Set the flag in your environment (or the equivalent key in your CLI configuration):

export RUDDERSTACK_X_ENABLE_VAR_SUBSTITUTION=true

Write variable references in YAML

Write each substituted field as {{ .VARIABLE_NAME }}. The name must match a key in the var file.

Use a variable for every secret field. Don’t put the credential in the spec as a literal.

See Amazon S3 configuration and the Account Resources YAML Reference for the full key lists.

Write Amazon S3 access keys

config:
  bucket_name: "my-rudder-bucket"
  role_based_auth: false
  access_key_id: "{{ .AWS_ACCESS_KEY_ID }}"
  access_key: "{{ .AWS_SECRET_ACCESS_KEY }}"

Write BigQuery account credentials

config:
  project: "acme-analytics-prod"
  location: "US"
  credentials: '{{ .BQ_CREDENTIALS }}'

Create a var file

Create credentials.vars.yaml with keys that match the names in your specs:

AWS_ACCESS_KEY_ID: "AKIA..."
AWS_SECRET_ACCESS_KEY: "wJal..."
BQ_CREDENTIALS: '{"type":"service_account","project_id":"acme-analytics-prod","private_key":"..."}'

Store the file next to the project, or at any path you can pass to --var-file. It holds real credentials.

Apply with a var file

Pass --var-file on apply so Rudder CLI resolves the references before it sends the payload:

rudder-cli apply --location ./project --var-file ./credentials.vars.yaml

You can combine --var-file with --dry-run to preview the workspace changes first.

Secrets are never read back. The RudderStack API doesn’t return credential values, so Rudder CLI can’t compare the remote secret against your local one. It re-sends the secret on every apply. A re-apply that reports a change to a secret field is expected, not drift.

Keep the var file out of version control

Add the var file to .gitignore. Commit the specs that contain {{ .VAR }} references; keep the resolved values local or in your CI secret store. In CI, write the var file at job time and pass --var-file on apply.

Fill placeholders after import

rudder-cli import workspace writes secret fields as {{ .VAR }} placeholders rather than values.

For warehouse accounts, import also scaffolds secrets.vars.yaml under imported/ — one placeholder line per variable the generated specs reference. Fill each placeholder with the real credential, then apply with --var-file.

An unfilled (null) placeholder makes the apply fail rather than silently sending an empty credential. To send an empty value on purpose, set the key to "".

See How to Import Workspace Resources into Your Rudder CLI Project for the import workflow.

See more

• Destination YAML Reference for S3 secret keys
• Account Resources YAML Reference for warehouse credential keys
• End-to-End Walkthrough: Destinations with Rudder CLI
• Core Rudder CLI Commands Reference