Go Template CLI (tpl)

Render json, yaml, & toml with go templates from the command line.

The templates are executed with the text/template package. This means they come with the additional risks and benefits of the text template engine.

Synopsis

Usage: tpl [options] [templates]
Options:
  -f, --file stringArray     template file path. Can be specified multiple times
  -g, --glob stringArray     template file glob. Can be specified multiple times
  -n, --name string          if specified, execute the template with the given name
  -d, --decoder string       decoder to use for input data. Supported values: json, yaml, toml (default "json")
      --option stringArray   option to pass to the template engine. Can be specified multiple times
      --no-newline           do not print newline at the end of the output
  -h, --help                 show the help text
      --usage                show the short usage text
  -v, --version              show the version

Input Data

The input data is read from stdin via pipe or redirection. It is actually not required to provide any input data. If no input data is provided, the template is executed with nil data.

# Redirection
tpl '{{ . }}' < path/to/input.json
# Pipe
curl localhost | tpl '{{ . }}'
# nil data
tpl '{{ . }}'

Templates

The default templates name is _gotpl_default and positional arguments are parsed into this root template. That means while its possible to specify multiple arguments, they will overwrite each other unless they use the define keyword to define a named template that can be referenced later when executing the template. If a named template is parsed multiple times, the last one will override the previous ones.

Templates from the flags --file and --glob are parsed in the order they are specified. So the override rules of the text/template package apply. If a file with the same name is specified multiple times, the last one wins. Even if they are in different directories.

The behavior of the cli tries to stay consistent with the actual behavior of the go template engine.

If the default template exists it will be used unless the --name flag is specified. If no default template exists because no positional argument has been provided, the template with the given file name is used, as long as only one file has been parsed. If multiple files have been parsed, the --name flag is required to avoid ambiguity.

tpl '{{ . }}' --file foo.tpl --glob 'templates/*.tpl'         # default will be used
tpl --file foo.tpl                                            # foo.tpl will be used
tpl --file foo.tpl --glob 'templates/*.tpl' --name foo.tpl    # the --name flag is required to select a template by name

The ability to parse multiple templates makes sense when defining helper snippets and other named templates to reference using the builtin template keyword or the custom include function which can be used in pipelines.

note globs need to quotes to avoid shell expansion.

Decoders

By default input data is decoded as json and passed to the template to execute. It is possible to use an alternative decoder. The supported decoders are:

• json
• yaml
• toml

While json could technically be decoded using the yaml decoder, this is not done by default for performance reasons.

Options

The --options flag is passed to the template engine. Possible options can be found in the documentation of the template engine. The only option currently known is missingkey. Since the input data is decoded into interface{}, setting missingkey=zero will show <no value>, if the key does not exist, which is the same as the default. However, missingkey=error has some actual use cases.

Functions

Next to the builtin functions, Sprig functions and some custom function are available.

Installation

Binary

Download the binary from the release page. For example

curl -fsSL https://github.com/bluebrown/go-template-cli/releases/latest/download/tpl-linux-amd64 >tpl
chmod 755 tpl

Go

If you have go installed, you can use the go install command to install the binary.

go install github.com/bluebrown/go-template-cli/cmd/tpl@latest

Example

Review the examples directory, for more examples.

curl -s https://jsonplaceholder.typicode.com/users | tpl '<table>
  <caption>My Address Book</caption>
  <tr>
    <th>Name</th>
    <th>Email</th>
    <th>Phone</th>
    <th>Address</th>
  </tr>
  {{- range . }}
  <tr>
    <th>{{ .name }}</th>
    <td>{{ .email }}</td>
    <td>{{ .phone }}</td>
    <td>
      <ul>
        {{- range $key, $val := .address }} {{ if ne $key "geo" }}
        <li><strong>{{ $key }}:</strong> &nbsp; {{ $val }}</li>
        {{- end -}}
        {{ end }}
      </ul>
    </td>
  </tr>
  {{- end -}}
</table>'

Output

My Address Book

Name	Email	Phone	Address
Leanne Graham	[email protected]	1-770-736-8031 x56442	city:   Gwenborough street:   Kulas Light suite:   Apt. 556 zipcode:   92998-3874
Ervin Howell	[email protected]	010-692-6593 x09125	city:   Wisokyburgh street:   Victor Plains suite:   Suite 879 zipcode:   90566-7771
Clementine Bauch	[email protected]	1-463-123-4447	city:   McKenziehaven street:   Douglas Extension suite:   Suite 847 zipcode:   59590-4157
Patricia Lebsack	[email protected]	493-170-9623 x156	city:   South Elvis street:   Hoeger Mall suite:   Apt. 692 zipcode:   53919-4257
Chelsey Dietrich	[email protected]	(254)954-1289	city:   Roscoeview street:   Skiles Walks suite:   Suite 351 zipcode:   33263
Mrs. Dennis Schulist	[email protected]	1-477-935-8478 x6430	city:   South Christy street:   Norberto Crossing suite:   Apt. 950 zipcode:   23505-1337
Kurtis Weissnat	[email protected]	210.067.6132	city:   Howemouth street:   Rex Trail suite:   Suite 280 zipcode:   58804-1099
Nicholas Runolfsdottir V	[email protected]	586.493.6943 x140	city:   Aliyaview street:   Ellsworth Summit suite:   Suite 729 zipcode:   45169
Glenna Reichert	[email protected]	(775)976-6794 x41206	city:   Bartholomebury street:   Dayna Park suite:   Suite 449 zipcode:   76495-3109
Clementina DuBuque	[email protected]	024-648-3804	city:   Lebsackbury street:   Kattie Turnpike suite:   Suite 198 zipcode:   31428-2261