Environment variable interpolation

Use ${VAR} and ${VAR:-default} in rayfin.yml with Rayfin's .env resolution, type coercion, and missing-variable errors.

rayfin.yml supports shell-style interpolation so environment-specific values stay out of committed configuration.

Syntax

Syntax	Meaning
`${VAR}`	Substitute `VAR`; error if unset or empty.
`${VAR:-default}`	Substitute `VAR`, or `default` when unset or empty.

rayfin/.env

DEFINED=value
EMPTY=

rayfin/rayfin.yml

config1: ${DEFINED}
config2: ${EMPTY:-fallback}
config3: ${UNDEFINED:-fallback}

Usage

Basic substitution

rayfin/rayfin.yml

services:
  data:
    enabled: true
    dialect: ${DB_DIALECT:-mssql}
  auth:
    enabled: true
    fabric:
      enabled: true
    allowedRedirectUris:
      - https://${APP_HOSTNAME}/callback

rayfin/.env.example

DB_DIALECT=mssql
APP_HOSTNAME=example.contoso.com

Default values

rayfin/rayfin.yml

services:
  data:
    dialect: ${DB_DIALECT:-mssql}

Partial interpolation

rayfin/rayfin.yml

services:
  auth:
    allowedRedirectUris:
      - https://${APP_HOSTNAME}/callback

`.env` file location

By default, Rayfin loads rayfin/.env. Override it with a command flag or shell variable:

npx rayfin up --env-file .\deploy\production.env

set RAYFIN_ENV_FILE=.\deploy\staging.env
npx rayfin up

Resolution priority

Shell environment variables, when non-empty.
Variables from --env-file <path> or RAYFIN_ENV_FILE, when non-empty.
Variables from rayfin/.env, when non-empty.
Default values from ${VAR:-default}.
Error when no value or default exists.

See Environment variables for the broader CLI environment reference.

Type coercion

When the entire YAML value is one interpolation expression, Rayfin coerces strings to the matching YAML scalar type:

rayfin/rayfin.yml

services:
  data:
    enabled: ${DATA_ENABLED}
    dialect: ${DB_DIALECT:-mssql}
  auth:
    expiryInMinutes: ${TOKEN_EXPIRY_MINUTES:-60}

rayfin/.env

DATA_ENABLED=true
TOKEN_EXPIRY_MINUTES=60

Partial interpolation always returns a string:

rayfin/rayfin.yml

services:
  staticHosting:
    folder: dist-${BUILD_NUMBER}

Error handling

A required missing variable fails before deployment:

❌ Environment variable 'DB_HOST' referenced in rayfin.yml (services.data.host) is not defined.
   Set it in .env file or shell environment.

Security best practices

Do not commit rayfin/.env; it is gitignored by scaffolded projects.
Commit rayfin/.env.example with placeholders for required variables.
Use CI secret variables for deployment secrets.
Omit defaults for values that must be supplied intentionally.

PromptParameterize a rayfin.yml value

Update rayfin/rayfin.yml so `services.data.dialect` reads from `${DB_DIALECT:-mssql}`.
Add `DB_DIALECT=mssql` to rayfin/.env.example, then run `npx rayfin up --dry-run` to
confirm interpolation resolves.

Something wrong on this page?Report an issueEdit this page

Environment variable interpolation

On this page