Variables and prompting

Declaring variables

Variables are declared as an ordered list in the sidecar:

variables:
  - name: app_name
    description: "Name of the application"
    type: str
    default: "myapp"

  - name: replicas
    type: int
    default: 3

  - name: enable_metrics
    type: bool
    default: true

  - name: runtime
    type: choice
    choices: ["go", "python", "node"]
    default: "go"

Field	Required	Notes
name	yes	The identifier used inside template files
description	no	Shown by template variables; used as prompt help
type	no	str (default), int, bool, choice
default	no	Any YAML scalar; keeps its YAML type
choices	only for choice	List of allowed values

Validation is strict in both directions: type: choice without choices is an error, and choices on a non-choice variable is also an error. An unknown type is rejected.

Resolution order

At apply time each variable resolves through three steps, first match wins:

1. --var key=value on the command line
2. default from the sidecar
3. Interactive prompt

deckctl template apply go-service ./out \
  --source local \
  --var app_name=billing \
  --var replicas=5

--var is repeatable. The value is everything after the first =, so --var motd=key=value sets motd to key=value. A --var entry with no = is silently ignored.

Caution

Values coming from --var are always strings. A sidecar default: 3 reaches the template as an integer, but --var replicas=3 reaches it as "3". This matters for arithmetic and for {% if %} on booleans — see Authoring templates.

Inspecting before applying

deckctl template variables go-service --source local

┌────────────────┬────────┬─────────┬────────────────────┬─────────────────────────┐
│ Name           │ Type   │ Default │ Choices            │ Description             │
├────────────────┼────────┼─────────┼────────────────────┼─────────────────────────┤
│ app_name       │ str    │ myapp   │                    │ Name of the application │
│ replicas       │ int    │ 3       │                    │                         │
│ enable_metrics │ bool   │ true    │                    │                         │
│ runtime        │ choice │ go      │ go, python, node   │ Runtime to target       │
└────────────────┴────────┴─────────┴────────────────────┴─────────────────────────┘

This command fetches the template but never renders or writes anything, so it is safe to run against anything. -o json gives you the raw declarations:

deckctl template variables go-service --source local -o json

[
  { "name": "app_name", "description": "Name of the application", "default": "myapp", "type": "str" },
  { "name": "runtime", "default": "go", "type": "choice", "choices": ["go", "python", "node"] }
]

Prompting

Any variable left without a value after steps 1 and 2 is prompted for, one at a time, using huh.

Current limitation

Prompts are free-text inputs for every type — type and choices are metadata for template variables and validation, not a constrained picker at the prompt. Nothing stops you typing a value outside choices, and typed input arrives as a string. If that matters, pass the value with --var or give it a default.

Avoiding prompts entirely

For scripts and CI, make sure every variable resolves before the prompt step:

deckctl template apply go-service ./out \
  --source work \
  --tag v1.2.3 \
  --var app_name=billing \
  --var replicas=5 \
  --var enable_metrics=true \
  --var runtime=go

--source itself is prompted for when omitted, so always pass it in automation. See Using deckctl in CI.

Copier templates

Copier questions map onto the same model, with two extra capabilities: Jinja-computed defaults and when conditions. See Copier compatibility.