jq has quickly become one of my favorite command-line utilities. I first heard about it from the YouTuber Primegen earlier this year but didn’t quite used it. I started using it around March or April for my work, and it’s been awesome.

First and foremost, what is it? jq is a command-line utility for processing JSON data. It has many use cases, some of which include:

1. Pretty Printing#

Say you curl some endpoint and receive verbose JSON. Often, the output on the terminal is messy and displeasing to the eye. You can pipe the output of curl (which will be in JSON format) to jq, and you will see a visually more readable output of your JSON.

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq

2. Selecting Specific Fields#

jq allows you to extract specific fields from a JSON structure, which is useful when you’re only interested in certain pieces of the data. For example, to access only the accounts array from the fetched data:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq '.accounts'

This snippet filters the entire JSON output, returning only the content of the accounts array.

You can also use jq to retrieve specific elements from an array based on their index. For instance, to get the first account in the accounts array:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq '.accounts[1]'

This command selects the second element from the accounts array (since indexing starts at 0).

3. Calculating Array Length#

To find out how many items are in an array, you can use the following command:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq '.accounts | length'

This returns the number of elements in the accounts array.

4. Filtering Based on Conditions#

jq is handy for filtering JSON data based on specific conditions. For example, to display only the accounts where the pub_key field is not null:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq '.accounts[] | select(.pub_key != null)'

5. Dealing with Data Types#

Sometimes, JSON fields are not in the data type you need them to be for further processing. jq allows you to convert these fields into appropriate types. If you need to filter accounts based on a numerical condition but the relevant field is stored as a string, jq can convert it:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq '.accounts[] | select((.sequence | tonumber) > 5)'

This command converts the sequence field to a number and selects accounts where the sequence is greater than 5.

6. Extracting Raw Values#

Sometimes, when working with JSON data, you might want to extract values in their raw form, without JSON-specific formatting like quotes around strings. jq provides a simple way to do this using the -r or --raw-output flag.

For example, if you want to retrieve the sequence value from the first account in the accounts array directly as a raw value, you can modify the jq command as follows:

curl https://emerynet.api.agoric.net/cosmos/auth/v1beta1/accounts | jq -r '.accounts[0].sequence'