JSON(1) General Commands Manual JSON(1)

json — A simple command line utility for parsing and generating JSON.

json [-s query] [-e str]

json is a simple command line utility for dealing with JSON. It is somewhat inspired by jq(1), but is not compatible in any way with it. json is designed to be much simpler than jq(1), and is built on Telodendria's own Json(3) API. It primarily exists to ease development of Telodendria, and to make development possible without having to install any external tools.

The options are as follows. Unless stated otherwise, these options are mutually exclusive, and the last one specified takes precedence. All positional parameters are ignored.

query
Use query to query a field from a JSON object given on the standard input. The query syntax very vaguely resembles C code, but it is much more primitive. Multiple queries are separated by an arrow (``->''). This makes it trivial to drill down into nested objects and arrays.

To select a value from an object, just specify the key. To select an element from an array specify the key whose value is the array, and then use the C square bracket syntax to select an element.

A number of ``functions'' exist to make json more versatile. Functions are called by prefacing the key with a ``@'' symbol. Functions can appear anywhere in the query, provided they make sense within the context of the JSON object being processed. The available functions are as follows:

keys
When applied to an object, outputs an array of keys.
length
When applied to an array, outputs the number of elements in the array. When applied to a string, returns the number of bytes needed to store the decoded version of the string.
decode
When applied to a string, outputs the decoded version of the string.

When a key is prefaced with the ``^'' symbol, then instead of getting the value at that key, it is removed from the object, and the new object is passed along.

str
Encode str as a JSON string and print it to standard output. This is useful for generating JSON with shell scripts.

If no options are specified, then the default behavior of json is to read a JSON object given on the standard input and pretty-print it to the standard output, or print an error to standard error if the given input is invalid.

Get the error string of an error returned by a Matrix API endpoint:

json -s 'error->@decode'

Get the number of stages in the first flow listed in a list of user-interactive authentication flows:

json -s 'flows[0]->stages->@length'

Get the first stage of the first flow listed in a list of user-interactive authentication flows:

json -s 'flows[0]->stages[0]->@decode'

List the keys in a JSON object:

json -s '@keys'

Get the number of keys in a JSON object:

json -s '@keys->@length'

json exits with EXIT_SUCCESS if all command line options were valid and the given JSON object parses successfully. It exits with EXIT_FAILURE in all other scenarios.

March 12, 2023 Telodendria Project