boilerplates/.wiki/Core-Concepts-Variables.md

Variables

Variables are defined per template in template.json under the top-level variables array. There is no separate schema reference layer anymore, so the manifest is the source of truth.

Runtime Shape

Each entry in variables is a group. Each group contains items.

{
  "variables": [
    {
      "name": "general",
      "title": "General",
      "description": "Base settings",
      "items": [
        {
          "name": "service_name",
          "type": "str",
          "title": "Service name",
          "default": "my-service"
        },
        {
          "name": "environment",
          "type": "enum",
          "title": "Environment",
          "value": "stage",
          "config": {
            "options": ["prod", "stage", "dev"]
          }
        }
      ]
    }
  ]
}

Group fields:

• name
• title
• description
• toggle
• needs
• items

Item fields:

• name
• type
• title
• description
• default
• value
• required
• needs
• extra
• config

Runtime mapping notes:

• title is used as the prompt label
• description is used as the display/help text
• if description is omitted, the runtime falls back to title

Supported Types

• str
• int
• float
• bool
• enum
• email
• url
• hostname
• secret

Type notes:

• bool defaults to false when omitted
• other types default to empty unless a default or value is provided
• secret values are masked in prompts and display output

default vs value

Use default for the normal manifest default.

Use value when the template should pin the runtime value directly. If both are present, value wins.

Example:

{
  "name": "environment",
  "type": "enum",
  "title": "Environment",
  "default": "prod",
  "value": "stage",
  "config": {
    "options": ["prod", "stage", "dev"]
  }
}

Config Object

Additional behavior is configured through config.

Supported fields:

• placeholder
• textarea
• unit
• options
• slider
• min
• max
• step
• autogenerated

Enum Options

{
  "name": "environment",
  "type": "enum",
  "title": "Environment",
  "config": {
    "options": ["prod", "stage", "dev"]
  }
}

Textarea Input

{
  "name": "notes",
  "type": "str",
  "title": "Notes",
  "config": {
    "textarea": true,
    "placeholder": "Optional notes"
  }
}

Integer Slider

{
  "name": "replicas",
  "type": "int",
  "title": "Replicas",
  "default": 3,
  "config": {
    "slider": true,
    "min": 1,
    "max": 9,
    "step": 2,
    "unit": "nodes"
  }
}

Autogenerated Secrets

config.autogenerated is supported only for secret variables.

Character-based example:

{
  "name": "database_password",
  "type": "secret",
  "title": "Database password",
  "config": {
    "autogenerated": {
      "kind": "characters",
      "length": 40,
      "characters": ["A", "B", "1", "2"]
    }
  }
}

Base64 example:

{
  "name": "api_token",
  "type": "secret",
  "title": "API token",
  "config": {
    "autogenerated": {
      "kind": "base64",
      "bytes": 12
    }
  }
}

Rules:

• autogenerated secrets cannot define default
• base64 generation uses bytes, not length
• autogenerated on non-secret variables is rejected

Dependencies with needs

Both groups and items support needs.

Examples:

• "needs": "traefik_enabled=true"
• "needs": "network_mode=bridge,macvlan"
• "needs": "network_mode!=host"
• "needs": "traefik_enabled=true;network_mode=bridge"

Semantics:

• semicolon means AND
• comma means OR within a single comparison
• = means the value must match
• != means the value must not match

Behavior notes:

• group needs controls whether the group is considered available
• item needs controls whether the item is shown and validated
• disabled boolean items are reset to false unless they were explicitly set via CLI

Group Toggles

Groups may define toggle, but the referenced toggle variable must exist as a boolean item in that same group.

{
  "name": "traefik",
  "title": "Traefik",
  "toggle": "traefik_enabled",
  "items": [
    {
      "name": "traefik_enabled",
      "type": "bool",
      "title": "Enable Traefik",
      "default": false
    },
    {
      "name": "traefik_host",
      "type": "hostname",
      "title": "Hostname"
    }
  ]
}

If the toggle variable is missing, the runtime ignores the toggle.

Override Order

For a loaded template, values are applied in this order:

1. default / value from template.json
2. saved defaults from the active config file
3. --var-file
4. --var
5. interactive prompt answers

Inspecting Variables

Use show against the template you care about:

boilerplates compose show nginx
boilerplates terraform show cloudflare-dns-record

That view reflects the actual runtime state for that template, including defaults, dependencies, toggle state, and file structure.