Yatera
Yet another Tera template v2 CLI.
It features rich DX and extra built-ins.
Installation
#Install Yatera on macOS or Linux by running the following command in your terminal:
curl -fsSL https://yatera.fyi/install.sh | shInstall Yatera on Windows by running the following command in PowerShell:
irm https://yatera.fyi/install.ps1 | iexInstall Yatera using Cargo Binstall by running the following command in your terminal:
cargo binstall yateraTo compile Yatera from source code, install Rust and then install Yatera using Cargo:
cargo install yateraUsage
#CLI
#Use the tera command to render templates from stdin:
# Render a template with variables:
cat template.tera | tera var1=value var2=value > output.txt
# Use structured data as variables (JSON/TOML/YAML):
cat template.tera | tera --json '{"var":"value"}' > output.txt
cat template.tera | tera --json-file vars.json > output.txt
# Read and write files directly:
tera --in-file template.tera --out-file output.txt --json-file vars.jsonEnvironment sources parse the variable's contents as JSON, TOML, or YAML. Choose
one structured context source; name=value arguments override its values.
Missing variables or invalid context contents produce an error.
Input
#By default Yatera reads the template from stdin. You can override this behavior by using the --in-file option to specify a template file:
tera --in-file template.tera > output.txtOutput
#By default Yatera writes the rendered result to stdout. You can override this behavior by using the --out-file option to specify an output file:
tera --in-file template.tera --out-file output.txtVariables
#Yatera supports multiple ways to provide template variables, from passing arguments to JSON/TOML/YAML strings or files.
Argument Variables
#To provide template variables directly as command-line arguments, use the name=value format:
cat template.tera | tera var1=value var2=value > output.txtAlternatively, use repeatable --var NAME VALUE flags, or the jq-compatible
--arg NAME VALUE alias:
cat template.tera | tera --var var1 value --var var2 value > output.txt
cat template.tera | tera --arg var1 value --arg var2 value > output.txtVariable Files
#To read variables from JSON/TOML/YAML files:
cat template.tera | tera --json-file vars.json > output.txtCLI options:
| Argument | Format |
|---|---|
--json-file vars.json |
JSON |
--toml-file vars.toml |
TOML |
--yaml-file vars.yaml |
YAML |
Variable Strings
#To read variables from JSON/TOML/YAML strings:
cat template.tera | tera --json '{"var":"value"}' > output.txtCLI options:
| Argument | Format |
|---|---|
--json '{"var":"value"}' |
JSON |
--toml "$(cat vars.toml)" |
TOML |
--yaml "$(cat vars.yaml)" |
YAML |
Environment Variable Strings
#Yatera also supports reading variables from JSON/TOML/YAML strings stored in environment variables:
export VARS='{"var":"value"}'
cat template.tera | tera --json-env VARSCLI options:
| Argument | Format |
|---|---|
--json-env VARS |
JSON |
--toml-env VARS |
TOML |
--yaml-env VARS |
YAML |
Lua Plugins
#Load Lua plugins in order with repeatable --plugin flags:
tera --in-file template.tera --json-file vars.json \
--plugin ./path/to/plugin1.lua --plugin ./path/to/plugin2.luaPlugins register filters, functions, and tests by assigning functions to the
yatera tables:
-- {{ name | greet(prefix="Hi") }}
yatera.filters.greet = function(value, args)
return (args.prefix or "Hello") .. ", " .. value .. "!"
end
-- {{ project_names() }}
yatera.functions.project_names = function(args)
local names = ""
for i, name in ipairs(yatera.get("projects") or {}) do
if i > 1 then names = names .. ", " end
names = names .. string.upper(name)
end
return names
end
-- {% if name is long(min=3) %}...{% endif %}
yatera.tests.long = function(value, args)
return #value >= (args.min or 3)
endRuntime API
#yatera.filters.NAME(value, args): receives the filtered value and named arguments.yatera.functions.NAME(args): receives named arguments.yatera.tests.NAME(value, args): receives the tested value and named arguments; must return a boolean.yatera.context: a table of additional template variables, merged into the input after all plugins load and before rendering. Lua values override matching top-level input keys (nested objects are replaced, not deep-merged). Plugins share this table in load order. Changes inside filters/functions happen after this merge and do not update the template context.yatera.get("name"): readsyatera.contextfirst, then the original render input, ornilif absent. This includes CLI variable overrides, but not Tera loop variables or{% set %}assignments. Pass those as filter values or named arguments instead.yatera.null: represents an explicit JSON null, including within arrays/objects.- Lua helpers include
pairs,ipairs,tostring,tonumber,assert,error, and the runtime'sstring,table, andmathlibraries.
For example, add variables alongside the playground's JSON input:
local home = yatera.get("home") or "/home/me"
local ssh_agent = yatera.get("ssh_agent") or "none"
yatera.context.env = { HOME = home }
yatera.context.mise_env = ssh_agent == "none" and "" or ssh_agentThe template can then use {{ env.HOME }} and {{ mise_env }}. The caller's
original Rust context is not modified.
Yatera embeds Piccolo, a pure-Rust Lua runtime, on both native and WebAssembly targets. Its core standard library is available; it is not a complete implementation of every PUC Lua standard-library function. File/process APIs and external module loading are not provided.
Objects become string-keyed Lua tables; arrays become 1-based tables; scalars keep
their types. Input arrays preserve their array identity, including empty arrays.
Returned consecutive integer-keyed tables become arrays, and string-keyed tables
become objects (an untagged empty {} is an object). Return nil or yatera.null
for null. Cycles, mixed/sparse table keys, non-finite numbers, and unsupported return
types produce render errors. Integers must fit Lua's signed 64-bit range.
Each render starts a fresh runtime. Plugins share globals within that render and are evaluated in the order supplied; later definitions replace earlier ones, including same-named built-ins. Top-level code and each callback have an execution budget so runaway Lua loops produce errors. Syntax/runtime errors fail the render without writing partial CLI output.
The playground has a Lua plugin tab in the Input pane. Its example is placeholder text only; enter code to activate a plugin.
Built-Ins
#Yatera supports all default Tera built-ins as well as extra filters.
Extra Filters
#heck
#heck methods are available as string filters:
printf '{{ name | snake_case }}' | tera name="Hello World"
#=> hello_world| Filter | Result for Hello World |
|---|---|
upper_camel_case / pascal_case |
HelloWorld |
lower_camel_case |
helloWorld |
snake_case |
hello_world |
kebab_case |
hello-world |
shouty_snake_case |
HELLO_WORLD |
shouty_kebab_case |
HELLO-WORLD |
train_case |
Hello-World |
Rust Library
#Add Yatera to your project with cargo add yatera, then render with a hash map:
use std::collections::HashMap;
fn main() -> Result<(), yatera::Error> {
let vars = HashMap::from([("name".to_owned(), "Hello World")]);
let output: String = yatera::render("{{ name | snake_case }}", &vars)?;
assert_eq!(output, "hello_world");
Ok(())
}Values may be strings or other serializable values, such as serde_json::Value for mixed types.
For an existing yatera::Context, use:
yatera::render_with_context(template, &context)Pass Lua source code as Vec<String> with render_with_plugins:
let plugins = vec![r#"
yatera.filters.shout = function(value, args)
return string.upper(value) .. "!"
end
"#.to_owned()];
let output = yatera::render_with_plugins("{{ name | shout }}", &vars, plugins)?;For an existing context, use
yatera::render_with_context_and_plugins(template, &context, plugins).