Overview The jq command is a lightweight JSON processor built into Nash. It allows you to parse, filter, and transform JSON data using a query syntax inspired by the popular jq tool.
Syntax jq [OPTIONS] FILTER [FILE...]
Options Compact output. Produces single-line JSON without pretty formatting.
Raw output. Outputs strings without JSON quotes (useful for extracting plain text values).
Null input. Starts with null as input instead of reading from stdin or files.
Supported Filters Identity Filter Basic usage
Compact output
echo '{"name":"Nash"}' | jq . # Output: # { # "name": "Nash" # }
Object Key Access Access object properties using .key syntax:
echo '{"name":"Nash","version":"1.0"}' | jq .name # Output: "Nash"
Chained Key Access Access nested properties with dot notation:
echo '{"user":{"name":"Alice","age":30}}' | jq .user.name # Output: "Alice"
Array Index Access Access array elements by index using .[N]:
echo '["apple","banana","cherry"]' | jq .[1] # Output: "banana"
Bracket Key Access Access object keys using bracket notation .["key"]:
echo '{"my-key":"value"}' | jq .["my-key"] # Output: "value"
Array/Object Iteration Iterate over all elements using .[]:
echo '[1,2,3]' | jq .[] # Output: # [ # 1, # 2, # 3 # ]
echo '{"a":1,"b":2}' | jq .[] # Output: # [ # 1, # 2 # ]
Built-in Functions keys Get all keys from an object or indices from an array:
echo '{"name":"Nash","type":"shell"}' | jq keys # Output: # [ # "name", # "type" # ]
echo '["a","b","c"]' | jq keys # Output: # [ # 0, # 1, # 2 # ]
values Get all values from an object or array:
echo '{"name":"Nash","version":"1.0"}' | jq values # Output: # [ # "Nash", # "1.0" # ]
length Get the length of arrays, objects, or strings:
echo '[1,2,3,4,5]' | jq length # Output: 5
echo '{"a":1,"b":2}' | jq length # Output: 2
echo '"hello"' | jq length # Output: 5
type Get the JSON type of a value:
echo '"hello"' | jq type # Output: "string"
echo '42' | jq type # Output: "number"
echo '[1,2,3]' | jq type # Output: "array"
echo '{"key":"value"}' | jq type # Output: "object"
echo 'null' | jq type # Output: "null"
echo 'true' | jq type # Output: "boolean"
has(key) Check if an object has a specific key:
echo '{"name":"Nash"}' | jq 'has("name")' # Output: true
echo '{"name":"Nash"}' | jq 'has("version")' # Output: false
Examples echo '{"user":"alice","score":95}' | jq .score # Output: 95
Raw String Output echo '{"message":"Hello, World!"}' | jq -r .message # Output: Hello, World! # (no quotes)
Process JSON File Compact JSON cat config.json | jq -c . # Output: {"name":"Nash","version":"1.0"}
echo '{"response":{"data":{"items":[1,2,3]}}}' | jq .response.data.items # Output: # [ # 1, # 2, # 3 # ]
Get Array Length echo '{"users":["alice","bob","charlie"]}' | jq '.users | length' # Note: Nash jq doesn't support pipe syntax yet, use: echo '["alice","bob","charlie"]' | jq length # Output: 3
List All Keys cat package.json | jq keys
Check Key Existence echo '{"status":"ok"}' | jq 'has("status")' # Output: true
Practical Use Cases API Response Processing # Extract error message from API response echo '{"error":{"message":"Not found"}}' | jq -r .error.message
Configuration Validation # Check if required config keys exist test $( cat config.json | jq 'has("api_key")' ) = "true" && echo "Valid"
Data Inspection # Quickly view JSON structure cat large-file.json | jq keys
# Get version for deployment script VERSION = $( cat package.json | jq -r .version ) echo "Deploying version $VERSION "
Error Handling The jq command will return an error if:
The input is not valid JSON
The filter references a non-existent key (returns null)
A filter is applied to an incompatible type (e.g., .key on an array)
# Invalid JSON echo 'not json' | jq . # Error: jq: invalid JSON: ... # Filter on wrong type echo '[1,2,3]' | jq .key # Error: jq: .key on non-object
Notes
Missing keys return null rather than producing an error
The -r flag is particularly useful when extracting string values for shell variables
Null input mode (-n) is useful for generating JSON from scratch
Array indices are 0-based
grep - Filter text by patterncut - Extract fields from textsed - Stream editor for text transformationcat - Display file contents 