The data templating language
Jsonnet

Commandline Tool

The commandline tool "jsonnet" will evaluate Jsonnet and emit JSON on stdout. It can evaluate snippets of code (with -e), or files (by filename). It is actually a commandline wrapper around the C API, a convenient way to evaluate Jsonnet code from shell scripts, build tools, or languages that do not yet have a library binding.

Usage

The tool is self-documenting:

Jsonnet commandline interpreter v0.8.9
Typical Usage:
jsonnet [<cmd>] {<option>} <filename>
Where <cmd> is one of {eval, fmt} and defaults to eval.
Available eval options:
  -h / --help             This message
  -e / --exec             Treat filename as code
  -J / --jpath <dir>      Specify an additional library search dir
  -o / --output-file <file> Write to the output file rather than stdout
  -m / --multi <dir>      Write multiple files to the directory, list files on stdout
  -y / --yaml-stream      Write output as a YAML stream of JSON documents
  -S / --string           Expect a string, manifest as plain text
  -s / --max-stack <n>    Number of allowed stack frames
  -t / --max-trace <n>    Max length of stack trace before cropping
  --gc-min-objects <n>    Do not run garbage collector until this many
  --gc-growth-trigger <n> Run garbage collector after this amount of object growth
  --version               Print version
Available options for specifying values of 'external' variables:
Provide the value as a string:
  -V / --ext-str <var>[=<val>]     If <val> is omitted, get from environment var
<var>
       --ext-str-file <var>=<file> Read the string from the file
Provide a value as Jsonnet code:
  --ext-code <var>[=<code>]    If <code> is omitted, get from environment var
<var>
  --ext-code-file <var>=<file> Read the code from the file

Available options for specifying values of 'top-level arguments':
Provide the value as a string:
  -A / --tla-str <var>[=<val>]     If <val> is omitted, get from environment var
<var>
       --tla-str-file <var>=<file> Read the string from the file
Provide a value as Jsonnet code:
  --tla-code <var>[=<code>]    If <code> is omitted, get from environment var
<var>
  --tla-code-file <var>=<file> Read the code from the file

Available fmt options:
jsonnet fmt {<option>} <filename>
and <option> can be:
  -h / --help             This message
  -e / --exec             Treat filename as code
  -o / --output-file <file> Write to the output file rather than stdout
  -i / --in-place         Update the Jsonnet file in place.  Same as -o <filename>
  --test                  Exit with failure if reformatting changed the file.
  -n / --indent <n>       Number of spaces to indent by (default 0, means no change)
  --max-blank-lines <n>   Max vertical spacing, 0 means no change (default 2)
  --string-style <d|s|l>  Enforce double, single quotes or 'leave' (the default)
  --comment-style <h|s|l> # (h)  // (s)  or 'leave' (default) never changes she-bang
  --[no-]pretty-field-names Use syntax sugar for fields and indexing (on by default)
  --[no-]pad-arrays       [ 1, 2, 3 ] instead of [1, 2, 3]
  --[no-]pad-objects      { x: 1, x: 2 } instead of {x: 1, y: 2} (on by default)
  --debug-desugaring      Unparse the desugared AST without executing it
  --version               Print version

In all cases:
<filename> can be - (stdin)
Multichar options are expanded e.g. -abc becomes -a -b -c.
The -- option suppresses option processing for subsequent arguments.
Note that since filenames and jsonnet programs can begin with -, it is advised to
use -- if the argument is unknown, e.g. jsonnet -- "$FILENAME".

Example

Evaluating a file.

~/jsonnet/examples$ jsonnet landingpage.jsonnet
{
   "person1": {
      "name": "Alice",
      "welcome": "Hello Alice!"
   },
   "person2": {
      "name": "Bob",
      "welcome": "Hello Bob!"
   }
}

Evaluating a snippet.

~/jsonnet/examples$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
   "x": 10,
   "y": 11
}

Multiple file output

The Jsonnet commandline tool has a special mode for generating multiple JSON files from a single Jsonnet file. This can be useful if you want to avoid writing lots of small Jsonnet files, or if you want to take advantage of cross-references and interdependencies between the files. The idea is to create a single JSON structure, the top level of which defines the various files:

// multiple_output.jsonnet
{
    "a.json": {
        x: 1,
        y: $["b.json"].y,
    },
    "b.json": {
        x: $["a.json"].x,
        y: 2,
    },
}

When executed using jsonnet -m <dir>, this will write the generated JSON to files a.json and b.json in the given directory, instead of the whole thing being written to stdout. In order to integrate nicely with build tools like make, the files are not touched if they already contain the given content. To stdout is printed the list of target files, one per line. This makes it easy to drive other tools that operate on the JSON files, e.g. via xarg.

$ jsonnet -m . multiple_output.jsonnet
a.json
b.json
$ cat a.json 
{
   "x": 1,
   "y": 2
}
$ cat b.json 
{
   "x": 1,
   "y": 2
}