Expression Syntax

The $ reference system is used in set_env values and env defaults to wire dynamic values.

Syntax	Meaning
`$prop`	Property from enclosing resource
`$resource.prop`	Property from a named resource
`$components.name.prop`	Property from another component's provides
`$components.name.endpoint.prop`	Property from a named endpoint on another component
`$secrets.name`	App-wide generated secret
`${prop}`	Explicit braced form (same as `$prop`)
`${prop:-default}`	Reference with fallback value
`$$`	Literal `$` (escape)

flowchart TD
    A["$reference in set_env"] --> B{"Reference type?"}
    B -->|"Single segment: $host"| C["Enclosing resource property"]
    B -->|"Dot path: $resource.prop"| D["Named resource lookup"]
    B -->|"components.*"| E["Component endpoint"]
    B -->|"secrets.*"| F["App-wide secret"]
    C --> G["Resolved value"]
    D --> G
    E --> G
    F --> G

Resolution order for a path:

Starts with secrets -- app-wide secret lookup
Starts with components -- component endpoint lookup
Single segment -- enclosing resource property (e.g. $url inside a set_env block)
Multi-segment -- first segment is the resource name (defaults to type, overridden by name), rest is property path

Examples:

set_env:
  DATABASE_URL: $url                                          # resource property
  JDBC_URL: "jdbc:postgresql://${host}:${port}/${name}"       # composed template
  DB_PORT: "${port:-5432}"                                    # with fallback

env:
  BACKEND_URL:
    default: $components.backend.url                          # cross-component
  METRICS_URL:
    default: $components.backend.metrics.url                  # named endpoint
  SECRET_KEY_BASE: "$secrets.secret-key-base"                 # app-wide secret
  HOME_BIN: "$$HOME/bin"                                      # literal $