{"content":"# aux4/template\n\nRender Handlebars templates from the command line. Pass any parameters as flags and they become the template context, then the rendered result is written to standard output.\n\naux4/template is handy for generating configuration files, scaffolding boilerplate, producing reports, or building any text output from a reusable template plus a set of values.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/template\n`\n\n## System Dependencies\n\nThis package runs on Node.js. If it is not already available, the installer can provision it:\n\n- [brew](/r/public/packages/aux4/system-installer-brew)\n- [linux](/r/public/packages/aux4/system-installer-linux)\n\n## Usage\n\nGiven a template file template.hbs:\n\n`handlebars\nHello {{name}}\n`\n\nRender it by passing the value as a flag:\n\n`bash\naux4 template --file template.hbs --name David\n`\n\n`text\nHello David\n`\n\nEvery --key value flag you pass becomes a variable available in the template. Output is plain text (no HTML escaping), so characters like &, <, and > pass through verbatim.\n\n### Options\n\n- --file — Path to the Handlebars template file to render (required).\n- --data <file> — A JSON file (a single object) used as the base template context.\n- --output <file> — Write the rendered result to this file instead of standard output.\n- --inputStream true — Read JSON records from standard input and render the template once per record (see streaming below).\n- Any other --key value flag becomes a template variable.\n\n### Context sources and precedence\n\nThe template context can come from three places, applied lowest to highest precedence:\n\n1. --data <file> — base/default fields from a JSON object.\n2. A JSON record read from standard input (with --inputStream true; see streaming below).\n3. --key value flags — explicit overrides applied to every render.\n\nSo a flag always wins over a value from --data or a stream record. For example, with person.json containing {\"name\":\"David\",\"age\":30}:\n\n`bash\naux4 template --file person.hbs --data person.json --age 40\n`\n\n`text\nDavid 40\n`\n\nThe age flag overrides the age from the data file, while name comes from the file.\n\n### Streaming JSON records on standard input\n\nStandard input is only read when you pass --inputStream true. With it, the template is rendered once per JSON record read from stdin, and each result is written in order. Both newline-delimited JSON (one object per line) and a single top-level JSON array are accepted:\n\nTemplate row.hbs:\n\n`handlebars\n{{name}} is {{age}}\n`\n\n`bash\nprintf '{\"name\":\"Ada\",\"age\":36}\\n{\"name\":\"Linus\",\"age\":54}\\n' | aux4 template --file row.hbs --inputStream true\n`\n\n`text\nAda is 36\nLinus is 54\n`\n\nFlags still apply to every record, so --age 99 would force that value across the whole stream, and --data supplies shared defaults. An invalid record stops processing with a non-zero exit code.\n\nBecause stdin is read only with --inputStream true, plain --key value rendering never touches standard input — so it is safe to use inside a pipeline (for example a ... | while read loop) without redirecting < /dev/null.\n\n### Writing to a file\n\nWith --output <file>, nothing is written to standard output; the rendered result (including every record of a stream, in order) goes to the file. The file is overwritten each run, mirroring a > file redirect — to accumulate across runs, omit --output and use the shell:\n\n`bash\ncat records.ndjson | aux4 template --file row.hbs --inputStream true >> all.txt\n`\n\n### Arrays and objects\n\nList and object values are passed as JSON and are parsed automatically, so you can use Handlebars block helpers such as {{#each}}.\n\nTemplate list.hbs:\n\n`handlebars\nShopping list:\n{{#each items}}\n- {{this}}\n{{/each}}\n`\n\nCommand:\n\n`bash\naux4 template --file list.hbs --items '[\"apples\",\"bananas\",\"cherries\"]'\n`\n\n`text\nShopping list:\n- apples\n- bananas\n- cherries\n`\n\nObjects work the same way and can be accessed with dot notation:\n\n`bash\naux4 template --file card.hbs --user '{\"name\":\"Ada\",\"role\":\"admin\"}'\n`\n\n`handlebars\n{{user.name}} ({{user.role}})\n`\n\n`text\nAda (admin)\n`\n\nBecause templates use standard Handlebars, the built-in helpers {{#if}}, {{#unless}}, {{#each}}, and {{#with}} are all available.\n\n### Type helpers\n\nFlag values arrive as strings, so a few helpers are provided to interpret them. They can be used inline or as subexpressions:\n\n- bool — interpret a value as a boolean. Only explicit false-ish values (false, 0, no, off, or empty) are false; everything else is true.\n- int — parse an integer.\n- number — parse a floating-point number.\n- json — JSON-stringify a value ({{json value}}, or {{json value indent=2}} to pretty-print).\n- date — format a date value; {{date value}} returns an ISO string, {{date value \"YYYY-MM-DD HH:mm:ss\"}} formats it (UTC). Numeric input is treated as epoch milliseconds.\n- timestamp — convert a date value to a Unix epoch in seconds.\n\nBecause a flag is a string, {{#if flag}} is always true for a non-empty value (even --flag false). Use the bool helper for boolean flags:\n\n`bash\naux4 template --file feature.hbs --enabled false\n`\n\n`handlebars\n{{#if (bool enabled)}}Feature is on{{else}}Feature is off{{/if}}\n`\n\n`text\nFeature is off\n`\n\nThe date and timestamp helpers convert a value you supply rather than reading the current time, which keeps renders reproducible. To stamp the current time, pass it in (for example --now \"$(date -u +%FT%TZ)\").\n\n### The aux4 helper\n\nA built-in aux4 helper lets a template call another aux4 command and inline its output. The first argument is the command and the rest are its arguments:\n\n`handlebars\nInstalled version: {{aux4 \"version\"}}\n`\n\n`handlebars\nGreeting: {{aux4 \"template\" \"--file\" \"greeting.hbs\" \"--name\" \"World\"}}\n`\n\nThe command runs as aux4 <args...>` and its standard output (with trailing newlines trimmed) is inserted into the rendered result. Templates are executed as written, so only render templates you trust.\n\n## License\n\nThis package is licensed under the Apache License 2.0.\n"}