Template Config Reference

Every AgileBuilder template carries one config file at its root. The CLI looks for the following names in order and uses the first one found:

1. .agilebuilder.config.yaml
2. .agilebuilder.config.json

If neither exists, generation continues with the default config and prints a warning. The default config is equivalent to: variables.enabled: false, filePatterns.mode: all, patterns: ["**/*"], delimiter: "%", inquirerQuestions: [], and no hooks.

Full example:

version: '1.0'
name: service-template
description: Service starter
source:
  subdir: template
variables:
  enabled: true
  delimiter: "%"
  filePatterns:
    mode: include
    patterns:
      - "**/*.ts"
      - "package.json"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
      default: my-app
    - name: useAuth
      type: confirm
      message: Enable authentication?
      default: true
    - name: runtime
      type: list
      message: Runtime
      choices:
        - node
        - bun
hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn
market: {}

The config file itself is never copied into the generated output.

Top-Level Fields

version

• Type: string; defaults to '1.0'.
• The config format version. The current CLI reads it without branching on its value; keep it at '1.0'.

name / description

• Type: string; optional.
• Template name and description. Pure metadata — they do not affect generation.

source

Optional object describing where the template files live inside the repository.

Field	Type	Description
source.subdir	string	Points to the actual template file root inside the fetched template directory. Use it when the config file sits at the repository root but the files to generate live in a subdirectory such as template/.
source.type	'git' or 'editor'	Reserved. The CLI does not use it to decide how a template is fetched — the source is determined by command arguments, the resource definition, or the Cloud template definition.

source.subdir must be a relative path; absolute paths and .. segments are rejected with TEMPLATE_SUBDIR_UNSAFE.

variables: Variable Rendering

variables is an object; every subfield falls back to its default when omitted.

variables.enabled

• Type: boolean; default false.
• The master switch. When true, file contents are rendered and file paths are rendered too; when false, all files are copied verbatim.

variables.delimiter

• Type: string; default "%".
• The EJS delimiter — the character between <% and %>. The default % gives you the familiar <%= appName %> tags. Set it to ? and placeholders become <?= appName ?>.
• Compatibility: writing "<%" or "%>" by mistake is normalized back to "%".

variables.filePatterns

Controls which files get their contents rendered (full matching semantics in File Patterns and Hooks).

Field	Type	Default	Description
mode	all | include | exclude	all	all renders every non-binary file; include renders only files matching at least one pattern; exclude renders files matching no pattern. Invalid values fall back to all.
patterns	string array	["**/*"]	minimatch patterns matched against paths relative to the template root. An empty array is treated as ["**/*"].

Binary files are always copied as-is, regardless of the mode.

variables.inquirerQuestions

An array of interactive questions. Each question defines a variable: it is prompted in --interactive mode, and contributes default values and required validation. Entries missing name or message are ignored.

Field	Type	Description
name	string (required)	The variable name referenced as <%= name %> in templates.
type	string	Question type; only input, number, confirm, list, checkbox, and password are supported. Defaults to input.
message	string (required)	The prompt text.
default	any	Default value, applied only while the variable is still missing.
required	boolean	When true, generation validates the variable is non-empty and fails with TEMPLATE_VARS_MISSING otherwise.
choices	array	Options for list / checkbox; items can be strings or { name, value } objects.

How each type behaves in interactive mode:

type	Prompt widget	Resulting value type
input	Single-line input	string
number	Number input	number
confirm	Yes/no confirmation	boolean
list	Single-select list	the chosen item's value
checkbox	Multi-select list	array of chosen values
password	Masked input	string

Note: question types only affect interactive prompting and defaults — they do not constrain values passed via --var / --vars (--var values are parsed as scalars: true/false/null/numbers). Variable precedence is documented in the CLI Reference.

hooks: Post-Generation Hooks

hooks is an object keyed by stage name. Only the after_write stage is processed today, and only scriptType: shell can execute.

hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn
    env:
      NPM_CONFIG_REGISTRY: https://registry.npmjs.org

Field	Type	Default	Description
scriptType	shell | nodejs | custom	shell	Only shell can execute today; other types fail with HOOK_TYPE_UNSUPPORTED once hooks are authorized.
script	string (required)	—	Shell command executed in the target directory. Hook entries without a script are ignored.
errorHandling	stop | warn | continue	stop	stop aborts generation on hook failure (HOOK_FAILED); warn / continue record the hook as skipped and keep going.
env	key-value object	—	Extra environment variables merged with the process environment for the hook.

Hooks do not run by default — they require explicit authorization via --allow-hooks or template.allowHooksDefault: true, and time out after 5 minutes. See File Patterns and Hooks for the execution model and security design.

market: Reserved Field

• Type: any object; optional.
• A metadata slot reserved for the template marketplace (categories, icons, display copy, and so on). The CLI parses and preserves the field, but generation never consumes it. For now, feel free to store your own extension metadata here or leave it empty.

Normalization Cheat Sheet

The CLI normalizes config leniently on load. Knowing these rules avoids surprises:

• Non-string version → '1.0'.
• Non-boolean variables.enabled → false.
• Invalid filePatterns.mode → all; non-array patterns → ["**/*"]; non-string pattern items are dropped.
• Empty or non-string delimiter → "%"; "<%" / "%>" → "%".
• Questions missing name / message → dropped entirely; missing type → input.
• Hooks missing script → ignored; invalid scriptType → shell; invalid errorHandling → stop; non-string env values are dropped.
• A config file that is not valid YAML/JSON → TEMPLATE_CONFIG_INVALID.