atmos scaffold generate

Generate a component, configuration, or project shape from a template. The template's versioned manifest owns its fields, conditions, files, hooks, and update provenance.

atmos scaffold generate --help

Usage

atmos scaffold generate [template] [target] [flags]

Examples

# Prompt for active fields and generate into a new directory.
atmos scaffold generate terraform-component ./components/terraform/vpc

# Supply values for automation; defaults satisfy required fields.
atmos scaffold generate terraform-component ./components/terraform/vpc \
  --defaults \
  --set component_name=vpc \
  --set environments=dev,staging

# Preview a template without writing files or running generation hooks.
atmos scaffold generate terraform-component ./preview --dry-run --skip-hooks

# Bring a recorded project forward after its template changes.
atmos scaffold generate terraform-component ./components/terraform/vpc \
  --update --merge-strategy=manual

# Force line-oriented text merging so YAML formatting (e.g. blank lines) survives an update.
atmos scaffold generate terraform-component ./components/terraform/vpc \
  --update --merge-driver=text

Template Sources

Select an embedded template, a template declared under scaffold.templates in atmos.yaml, or a local/remote source. A source can be pinned with --ref to make a release, tag, or commit explicit.

atmos scaffold list
atmos scaffold generate ./scaffolds/terraform-component ./components/terraform/vpc
atmos scaffold generate https://github.com/example/platform-templates.git ./output --ref v1.2.0

Template Configuration

Use the versioned manifest below; the former top-level prompts: key is not valid.

scaffold.yaml

apiVersion: atmos/v1
kind: AtmosScaffoldConfig
metadata:
  name: terraform-component
spec:
  fields:
    - name: component_name
      label: Component name
      type: input
      required: true
      validation:
        pattern: "^[a-z0-9-]+$"
    - name: create_monitoring
      type: confirm
      default: false
    - name: alert_email
      type: input
      when: "answers.create_monitoring == true"
  files:
    - path: monitoring.tf
      when: "answers.create_monitoring == true"

Fields render into template content and paths through {{ .Config.<field> }}. Required, option, boolean, and regular-expression validation is enforced after all answer sources merge: interactive answers, defaults, saved spec.values, and --set. select and multiselect require values from their declared options; false remains a valid answer for a required boolean.

when: accepts predicate words, CEL, or an implicit-all list. Conditions can inspect only earlier field answers through answers; use CEL (&&, ||, !) for compound logic because the map-style {all, any, not} form is not accepted by scaffold manifests.

Dynamic File Generation

matrix: expands a single discovered file into one generated file per resolved combination — the Cartesian product of one or more axes, using the same axis shape the workflow matrix: step uses:

scaffold.yaml

spec:
  fields:
    - name: environments
      type: multiselect
      options: [dev, staging, production]
  files:
    - path: environment.yaml
      target: "stacks/{{ .matrix.environment }}.yaml"
      matrix:
        environment: answers.environments

An axis's value is a literal list declared directly in scaffold.yaml (e.g. region: [us-east-1, us-west-2]), a dot-path into answers.* referencing an already list-shaped answer, such as a multiselect field, or a Go-template expression (any string containing {{) that computes the list. --set values for a multiselect field are split on commas automatically, so --set environments=dev,staging works non-interactively.

Declaring more than one axis expands their full Cartesian product; add when: to prune combinations that don't apply, using the matrix CEL variable alongside answers:

scaffold.yaml

spec:
  files:
    - path: deploy.yaml
      target: "deploy/{{ .matrix.environment }}/{{ .matrix.region }}.yaml"
      matrix:
        environment: [dev, staging, production]
        region: [us-east-1, us-west-2]
      when: "matrix.region in answers.environments[matrix.environment].regions"

target: is required whenever matrix: is set. The resolved combination is available in target: and the file's own content — not just the output path — as .matrix.<axis>, matching Go template's leading-dot field access. when: is CEL, not Go template, so it reads the same value as matrix.<axis> instead, without the leading dot (see the when: example above). Two files (matrixed or not) rendering to the same output path is a hard error, never a silent overwrite.

An axis doesn't need to come from a multiselect at all — a plain free-text answer is just a string, and any Sprig/Gomplate function can split it into a list:

scaffold.yaml

spec:
  fields:
    - name: environments_csv
      type: input
      label: Comma-separated list of environments
  files:
    - path: deploy.yaml
      target: "deploy/{{ .matrix.environment }}.yaml"
      matrix:
        environment: '{{ splitList "," answers.environments_csv }}'

Typing dev,staging,production at the prompt generates the same three files a multiselect with those three options would — except the values aren't limited to a fixed, template-author-declared list.

When an axis's values aren't already list-shaped anywhere in answers — e.g. an answer is itself a map of structured values rather than a flat multiselect — compute the list with collectKeys, a template function unconditionally available to axis expressions, alongside every Sprig/Gomplate function. Scaffold templating always has both available and is independent of the templates.settings.sprig.enabled/templates.settings.gomplate.enabled settings, which only gate stack manifest templating. collectKeys(m) returns m's top-level keys, sorted; collectKeys(m, "nestedKey") collects nestedKey's own keys from every value in m, flattened and deduplicated:

scaffold.yaml

spec:
  files:
    - path: deploy.yaml
      target: "deploy/{{ .matrix.environment }}/{{ .matrix.region }}.yaml"
      matrix:
        environment: '{{ collectKeys answers.environments }}'
        region: '{{ collectKeys answers.environments "regions" }}'
      when: "matrix.region in answers.environments[matrix.environment].regions"

Given an environments answer shaped like this:

environments:
  dev:
    regions:
      us-east-1: {}
  production:
    regions:
      us-east-1: {}
      us-west-2: {}

environment resolves to dev and production, and region to every region used by any environment (us-east-1 and us-west-2) — when: then prunes the Cartesian product down to each environment's actual regions.

Generation Hooks

Generation hooks run after answers are validated and before or after files are written:

scaffold.yaml

spec:
  hooks:
    prepare:
      events: [before.scaffold.generate]
      kind: step
      type: shell
      with:
        command: mkdir -p generated
    validate:
      events: [after.scaffold.generate]
      kind: steps
      with:
        - type: shell
          command: terraform fmt -recursive
        - type: shell
          command: terraform validate

Scaffold hooks run in stable name order and support only kind: step and kind: steps. A single step hook uses its envelope type: plus step-specific with: data; a steps hook executes the ordered with: list. The shared envelope supplies events, when, env, retry, and on_failure. Use answers in hook CEL and {{ .Answers.<field> }} inside a step template.

Use --skip-hooks to skip all hooks or --skip-hooks=prepare,validate to skip named hooks. The stack-level hooks reference documents additional stack-only kinds such as scanners, stores, Git, and CI integrations.

Update and Safety Flags

--defaults

Use defaults and --set values without prompting.

--dry-run

Render a preview without generated-file writes.

--force

Permit generation into a non-empty target without update merging.

--update

Apply an optimistic three-way merge using the recorded source/base revision.

--merge-driver (default auto)

Choose auto (YAML-aware for .yaml/.yml, text otherwise) or text to force every file through the line-oriented text merge driver, preserving formatting (e.g. blank lines) that a YAML-aware re-encode would otherwise collapse.

--merge-strategy (default manual)

Choose manual, ours, or theirs for merge conflicts.

--skip-hooks

Skip all hooks or a comma-separated set of hook names.

--git / --no-git

Control initial Git setup; generation defaults to no Git initialization.

Related Commands

• atmos scaffold validate
• atmos scaffold list
• atmos init
• Lifecycle hooks