View on GitHub

JSONPath implementation in Bash for filtering, merging and modifying JSON


This is a JSONPath implementation written in Bash.

See how compares to other implementations:

Currently we rely on GNU implementations of the underlying tools. On OSX you can try wrapping the command like ./ ./

Invocation [-b] [-i] [-j] [-h] [-p] [-u] [-f FILE] [pattern]


the JSONPath query. Defaults to ‘$.*’ if not supplied.


Brief output. Only show the values, not the path and key.


Read a FILE instead of reading from standard input.


Case insensitive searching.


Output in JSON format, instead of format.


Strip unnecessary leading path elements.


Pass formatted data through to the JSON parser only. Useful after data has been manipulated.


Show help text.

Requirements is a Bash script that uses the standard GNU tools: bash, cat, sed, gawk, grep, and seq. NOTICE that gawk, gnu awk, is required, not mawk or nawk, but gawk.


Install with pip:

Install with npm:

Or copy the script to your PATH, for example:

curl -O
chmod +x
mv ~/bin


$ ./ < package.json
["name"]        ""
["version"]     "0.0.0"
["description"] "JSONPath implementation written in Bash"
["homepage"]    ""
["repository","type"]   "git"
["repository","url"]    ""
["bin",""]   "./"
["author"]      "Mark Clarkson <>"
["scripts","test"]      "./ ./"

more complex examples:


# Number of downloads yesterday
curl -s | \ '$.downloads' -b

# Show all versions
curl | ./ '$.versions.*.version'

# Show version 2.2.0
./ \
    -f test/valid/ \

# Find versions 2.2.x (using a regular expression)
# and show version and contributors
./ \
    -f test/valid/ \


# The default query
./ \
    -f test/valid/ \

# The same, but using a filter (script) expression
# (This takes 2 passes through the data)
./ \
    -f test/valid/ \


# Show the NodePort of a service named bob
# from a list of all services
kubectl get svc -o json | \
    '$..items[?(].spec.ports[0].nodePort' -b

# Or, more simply, show the NodePort of the service
kubectl get svc bob -o json | '$..nodePort' -b

# Get the port of the kubernetes-dashboard and output as json:
kubectl get svc --all-namespaces -o json | -j -u \


# Show Everything
./ -f test/valid/docker_stopped.json '$.*'

# Look for an ip address (using case insensitive searching to start)
./ \
    -f test/valid/docker_running.json \
    /valid/docker_running.json -i '$..".*ip.*"'

# Now get the IP address exactly
./ \
    -f test/valid/docker_running.json \
    '$.*.NetworkSettings.IPAddress' -b

# Show all Mounts
./ \
    -f test/valid/docker_stopped.json \

# Show sources and destinations for all mounts
./ \
    -f test/valid/docker_stopped.json \

# Use brief (-b) output to store mounts in an array for use in a loop
readarray -t MNTS \
  < <(./ -b -f test/valid/docker_stopped.json '$.*.Mounts[*].[Source,Destination]')

# the loop:
for idx in `seq 0 $((${#MNTS[*]}/2-1))`; do
    echo "'${MNTS[idx*2]}' is mounted on the host at '${MNTS[idx*2+1]}'"


# dot-notation (my latest favourite book)
./ \
    -f test/valid/ \

# dot-notation with a node set
./ \
    -f test/valid/ \

# bracket-notation ('$[' needs escaping at the
# command line, so bash doesn't think it's an
# arithmetic expression)
./ \
    -f test/valid/ \

# bracket-notation with an array slice and a set
./ \
    -f test/valid/ \

# Mixed bracket- and dot- notation
./ \
    -f test/valid/ \

# Show all titles
./ \
    -f test/valid/ \

# All books with 'Book 1' somewhere in the title
./ \
    -f test/valid/ \
    -i '$[?(@.title==".*Book 1.*")].title'

# All books with a price less than or equal to 4.20
# Show both the title and the price and output in
# JSON format but without redundant path elements.
./ -j -u \
    -f test/valid/ \

# The following does not work yet (TODO) 
./ \
    -f test/valid/ \

JSONPath patterns and extensions

Supported JSONPath options

JSONPath Supported Comment
$ Y the root object/element (optional)
@ Y the current object/element
. or [] Y child operator.
.. Y recursive descent.
* Y wildcard. All objects/elements regardless their names.
[] Y subscript operator.
[,] Y node sets.
[start:end:step] Y array slice operator.
?() Y applies a filter (script) expressions
() Y script expression, using the underlying script engine.

Searching for things


Use a regular expression inside the JSONPath pattern.
Combine with ‘-i’ for case insensitive search.
Combine with ‘-w’ to match whole words only.


Find every node key starting with ‘ip’:

# These are all equivalent
./ -f test/valid/docker_running.json -i "$..['ip.*']"
./ -f test/valid/docker_running.json -i '$..["ip.*"]'
./ -f test/valid/docker_running.json -i '$.."ip.*"'
./ -f test/valid/docker_running.json -i "$..'ip.*'"

Restrict the previous search to the bridge object.

./ -f test/valid/docker_running.json -i "$..bridge.'ip.*'"

Show all book titles by authors starting with ‘Doug’.

# Show the title
./ -f test/valid/ -i \

# Show the author, title and rating (can be with or without double quotes)
./ -f test/valid/ -i \


A common task is to modify JSON data on-the-fly. Unix style ‘one-liners’ can be created to easily and logically modify JSON data.

The key to data modification (that is: add, modify or deletion of data) is to modify the formatted data, then use the passthrough, ‘-p’, option to output again as JSON. Sequence is:

  1. Read JSON data and output as data.
  2. Modify data using standard Unix tools.
  3. Pipe modified data to with passthrough option producing JSON data again.

For example: The following ‘one-liner’ will read a kubernetes deployment configuration (using ‘kubectl get …’), output it in format (using ‘’), change the number of replicas from the existing value to 5 (using sed), output again in JSON (using ‘ -p’), then replace the original deployment with the newly changed one (using ‘kubectl replace …’).

kubectl get deployment sample-deployment -o json | \ | \
sed 's/\["spec","replicas"\].*/["spec","replicas"]\t5/' | \ -p | \
kubectl replace deployment sample-deployment -f -

This allows you to reuse your Unix skills rather than learn new terse syntax or Domain Specific Language.


This tool,, is really handy for handing json formatted data to other tools, and using pass-through mode (-p) comes in quite handy for creating complex queries and outputting in json.

Re-injection allows the user to overcome the limitation of a single filter expression per invocation. To do this the first query, or set of queries, should output in JSON format using the ‘-j’ option.

Usage Example

Show all books with a price greater than 4 that also have a 5 star rating (note that the first process in the pipeline outputs in json):

./ -j -f test/valid/ \
    '$[?(@.price>4)]' | ./ \

Pass-through mode reads the standard output (or produces and outputs JSON. This gives the user an opportunity to filter or modify the results:

Filtering Usage Example

Show all authors, without showing duplicates and output in JSON format.

All authors with duplicates:

$ ./ -f test/valid/ '$' 
... omitted ...
["store","book",9,"author"]     "James S. A. Corey"
["store","book",10,"author"]    "James S. A. Corey"
["store","book",11,"author"]    "James S. A. Corey"
... 25 lines of output ...

Use standard unix tools to remove duplicates:

$ ./ -f test/valid/ '$' \
    | sort -k2 | uniq -f 1 
... 11 lines of output ...

And pipe (re-inject - ‘cos it sounds cool) the output into

$ ./ -f test/valid/ '$' \
    | sort -k2 | uniq -f 1 \
    | ./ -p
                "author":"Douglas E. Richards"
                "author":"Evelyn Waugh"
... JSON output with unique data ...

Use the ‘-u’ option to flatten the output:

$ ./ -f test/valid/ \
    '$' \
    | sort -k2 | uniq -f 1 \
    | ./ -p -u
... JSON flattened output ...
            "author":"Douglas E. Richards" 
            "author":"Evelyn Waugh"

Filter and Merge Usage Example

Different parts of JSON input, or entirely different JSON input, can be merged together with Unix ‘sort’ and output in json format.

This is a complex kubernetes example that uses and standard Unix tools to output just the command, pod mounts, and container mounts (output from different parts of the tree) for the first matched kube-proxy pod.

# Get details of all pods
kubectl get -n kube-system pods -o json >/tmp/kpod

# Get the index of the first pod with name starting 'kube-proxy'
idx=` -f /tmp/kpod '$.items[?("kube-proxy.*")].apiVersion' \
     | head -n1 | grep -o ',[0-9]\+,' | tr -d ,`

# Get three subtrees using the index and merge them using sort
# and then output in json format
( -f /tmp/kpod '$.items['$idx'].spec.volumes'; \ -f /tmp/kpod '$.items['$idx']..volumeMounts'; \ -f /tmp/kpod '$.items['$idx']..containers[*].command'
) | sort | -p -u

, which produces:



Limitations (todo)


This software is available under the following licenses: