jdig command line

Usage

jdig [FILE] [--theme dark|light] [-q QUERY] [-o json|lines|count]

jdig FILE opens the file in the terminal viewer. With -q, jdig runs the query, prints the results, and exits without opening the viewer.

Options

Option	Does	Default
FILE	The JSON or NDJSON file to open. Without it, jdig reads JSON from a pipe.
-q, --query QUERY	Runs a query and prints the results. A query that starts with $ is JSONPath; anything else is jq.
-o, --output FORMAT	How -q prints the results: json, lines, or count	json
--theme THEME	dark or light. light shows null values in gray, for light terminal backgrounds.	dark
-h, --help	Shows the options
-V, --version	Shows the version

When something goes wrong, jdig prints error: and the reason to standard error and exits with code 1.

Piped input

Without a file, jdig reads JSON from standard input:

curl -s https://api.example.com/users | jdig
curl -s https://api.example.com/users | jdig -q '.[].email' -o lines

The input must be one JSON value; NDJSON cannot be piped. jdig reads the whole input into memory, so for a very large document, save it to a file and open the file instead.

Run queries in scripts

-q runs a jq or JSONPath query over the file and prints the results to standard output:

jdig orders.json -q '.orders[] | select(.status == "pending") | .id' -o lines

The first run on a large file takes longer than the next ones. On an NDJSON file, jq runs once per record; JSONPath needs a JSON file.

Standard error also gets a summary, such as 12 result(s) in 3.4ms, so redirect it if a script reads both streams.

Caution

-q prints at most 1,000 results, without a warning, so -o count never goes above 1,000. Narrow the query when you may get more. In scripts, use jq rather than JSONPath: JSONPath results are printed shortened, and strings with quotes or backslashes are not escaped.

Output formats

Format	Prints
json	Indented JSON. One result is printed as itself; no results, or several, as an array. Use lines to get one result per line in every case.
lines	One result per line: strings without quotes, other values as compact JSON. Use it with grep, sort, and xargs.
count	The number of results