How to Use Variable Substitution in Rudder CLI Beta

Variable substitution requires Rudder CLI v0.25.0 or later.

Upgrade if you are using an earlier version.

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

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.

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 Destination Type Reference for Rudder CLI for the secret keys of each destination type, and the Account Resources YAML Reference for account keys.

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 the secret fields it receives as {{ .VAR }} placeholders rather than values. For destinations, the imported YAML may or may not include every secret key, so before you apply, make sure each secret key the destination needs is present and populated through variable substitution.

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 existing secrets.vars.yaml is never overwritten, so values you’ve already filled in survive a re-import.

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

Once your project holds {{ .VAR }} references, pass --var-file to import workspace as well as to apply. Import loads and diffs the project before writing, so an unresolved reference reads as drift and fails the command. See Import a project that uses variable substitution.

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