CLI and Template Studio

The CLI and browser editor share the JavaScript runtime. They are designed for portable safe-html-v1 projects and produce ordinary HTML files alongside local assets.

CLI

Node.js 22 or newer is required.

npx @trafficops/cli --template ./campaign --output ./generated

Without --data, the command opens a terminal form generated from the template schema. Pass JSON for CI or scripted generation:

npx @trafficops/cli \
  --template ./campaign \
  --data ./values.json \
  --context ./context.json \
  --output ./generated \
  --force

Option	Purpose
-t, --template <path>	Required .tpl / .tpl.html file or project directory.
-d, --data <json>	JSON values; bypasses the interactive form.
-o, --output <directory>	Output directory, default ./generated.
--context <json>	Safe runtime query, locale, and actions.
-f, --force	Replace files generated by a previous run.

File mode and directory mode

• File mode reads one file and its include graph.
• Directory mode discovers entry pages and copies ordinary assets unchanged.
• .tpl and .tpl.html become .html; included fragments do not become pages.
• Hidden paths, node_modules, vendor, and symlinks are omitted.
• The output directory must be outside the source project.

With --force, the CLI replaces only paths generated by the current project and preserves unrelated output files.

Interactive controls

• arrow keys select choices;
• Space toggles booleans;
• Enter advances;
• Ctrl+U clears the current value;
• Ctrl+B goes back;
• Esc cancels.

Type \n for multiline content. Required fields and constraints are checked before generation.

Template Studio

Open Template Studio

The editor runs entirely in the browser:

1. create a project or open a ZIP containing .tpl / .tpl.html files and assets;
2. edit source in Monaco with highlighting, completion, and formatting;
3. fill the generated Customize form;
4. inspect desktop and mobile previews for every page;
5. download generated pages or the editable source ZIP.

Files and ZIP archives are not uploaded to an API. Changes live in the tab's memory, so download the template ZIP and settings JSON before closing it.

Preview boundary

Preview runs in a sandboxed iframe under a restrictive Content Security Policy. Scripts, forms, navigation, frames, and network connections are disabled. Local images, CSS, and fonts are mapped to temporary in-memory URLs; export keeps the original relative paths.

The preview is for static layout inspection, not full page execution. Its restrictions do not rewrite generated output.

Import limits

The editor rejects traversal, absolute, hidden, and duplicate paths, symlinks, encrypted archives, and ambiguous file/directory collisions. Primary limits are 20 MiB compressed ZIP, 32 MiB expanded data, 500 entries, and 8 MiB per file.

JavaScript runtime limits

The browser and CLI do not support application-owned PHP dialects, custom PHP field aliases, or named JSON partials. Use the PHP engine for host-specific behavior.

See the complete runtime/README.md compatibility matrix and exact tops-cli/README.md command behavior.