Complete jq (JSON) commands reference — 193 commands across 10 categories. Quick reference cheat sheet for Linux, macOS & Windows.
jq is a filter language for JSON: a program is a chain of filters joined by pipes, each taking a JSON value and producing zero or more values. The table lists the operators and builtins from the jq manual; the notes below cover the dozen that handle most command-line work and the two ideas — streams and paths — that make the rest of the manual readable.
| Shortcut | Action |
|---|---|
| jq '.' | Identity |
| jq '.foo' | Object Identifier-Index |
| jq '.foo.bar' | Object Identifier-Index |
| jq '.foo?' | Optional Object Identifier-Index |
| jq '.[<string>]' | Object Index |
| jq '.[<number>]' | Array Index |
| jq '.[<number>:<number>]' | Array/String Slice |
| jq '.[]' | Array/Object Value Iterator |
| jq '.[]?' | Like .[], but no errors will be output if |
| jq '|' | Pipe |
| Shortcut | Action |
|---|---|
| jq '[]' | Array construction |
| jq '{}' | Object Construction |
| jq '..' | Recursive Descent |
| Shortcut | Action |
|---|---|
| jq '+' | Addition |
| jq '-' | Subtraction |
| jq '*' | Multiplication, division, modulo |
| jq '/' | Multiplication, division, modulo |
| jq '%' | Multiplication, division, modulo |
| jq 'abs' | The builtin function abs is defined naively as: if |
| jq 'length' | The builtin function length gets the length of various different types of value |
| jq 'utf8bytelength' | The builtin function utf8bytelength outputs the number of bytes used to encode a string in UTF- |
| jq 'keys' | The builtin function keys, when given an object, returns its keys in an array |
| jq 'keys_unsorted' | The builtin function keys, when given an object, returns its keys in an array |
| jq 'has(key)' | The builtin function has returns whether the input object has the given key, or the input array |
| jq 'in' | The builtin function in returns whether or not the input key is in the given object, or the inp |
| jq 'map(f)' | For any filter f, map(f) and map_values(f) apply f to each of the values in the input array |
| jq 'map_values(f)' | For any filter f, map(f) and map_values(f) apply f to each of the values in the input array |
| jq 'pick(pathexps)' | Emit the projection of the input object or array defined by the specified sequence of path expr |
| jq 'path(path_expression)' | Outputs array representations of the given path expression in .. The outputs are arrays |
| jq 'del(path_expression)' | The builtin function del removes a key and its corresponding value from an object |
| jq 'getpath(PATHS)' | The builtin function getpath outputs the values in . found at each path in PATHS |
| jq 'setpath(PATHS; VALUE)' | The builtin function setpath sets the PATHS in . to VALUE |
| jq 'delpaths(PATHS)' | The builtin function delpaths deletes the PATHS in .. PATHS must be an array of paths, where |
| jq 'to_entries' | These functions convert between an object and an array of key-value pairs |
| jq 'from_entries' | These functions convert between an object and an array of key-value pairs |
| jq 'with_entries(f)' | These functions convert between an object and an array of key-value pairs |
| jq 'select(boolean_expression)' | The function select(f) produces its input unchanged if f returns true for that input, and produ |
| jq 'arrays' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'objects' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'iterables' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'booleans' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'numbers' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'normals' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'finites' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'strings' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'nulls' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'values' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'scalars' | These built-ins select only inputs that are arrays, objects, iterables (arrays or objects), boo |
| jq 'empty' | empty returns no results |
| jq 'error' | Produces an error with the input value, or with the message given as the argument |
| jq 'error(message)' | Produces an error with the input value, or with the message given as the argument |
| jq 'halt' | Stops the jq program with no further outputs |
| jq 'halt_error' | Stops the jq program with no further outputs |
| jq 'halt_error(exit_code)' | Stops the jq program with no further outputs |
| jq '$__loc__' | Produces an object with a "file" key and a "line" key, with the filename and line number where |
| jq 'paths' | paths outputs the paths to all the elements in its input (except it does not output the empty l |
| jq 'paths(node_filter)' | paths outputs the paths to all the elements in its input (except it does not output the empty l |
| jq 'add' | The filter add takes as input an array, and produces as output the elements of the array added |
| jq 'add(generator)' | The filter add takes as input an array, and produces as output the elements of the array added |
| jq 'any' | The filter any takes as input an array of boolean values, and produces true as output if any |
| jq 'any(condition)' | The filter any takes as input an array of boolean values, and produces true as output if any |
| jq 'any(generator; condition)' | The filter any takes as input an array of boolean values, and produces true as output if any |
| jq 'all' | The filter all takes as input an array of boolean values, and produces true as output if all |
| jq 'all(condition)' | The filter all takes as input an array of boolean values, and produces true as output if all |
| jq 'all(generator; condition)' | The filter all takes as input an array of boolean values, and produces true as output if all |
| jq 'flatten' | The filter flatten takes as input an array of nested arrays, and produces a flat array |
| jq 'flatten(depth)' | The filter flatten takes as input an array of nested arrays, and produces a flat array |
| jq 'range(upto)' | The range function produces a range of numbers |
| jq 'range(from; upto)' | The range function produces a range of numbers |
| jq 'range(from; upto; by)' | The range function produces a range of numbers |
| jq 'floor' | The floor function returns the floor of its numeric input |
| jq 'sqrt' | The sqrt function returns the square root of its numeric input |
| jq 'tonumber' | The tonumber function parses its input as a number |
| jq 'toboolean' | The toboolean function parses its input as a boolean |
| jq 'tostring' | The tostring function prints its input as a string |
| jq 'type' | The type function returns the type of its argument as a string, which is one of null, boolean |
| jq 'infinite' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'nan' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'isinfinite' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'isnan' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'isfinite' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'isnormal' | Some arithmetic operations can yield infinities and "not a number" (NaN) values |
| jq 'sort' | The sort functions sorts its input, which must be an array |
| jq 'sort_by(path_expression)' | The sort functions sorts its input, which must be an array |
| jq 'group_by(path_expression)' | group_by(.foo) takes as input an array, groups the elements having the same .foo field into sep |
| jq 'min' | Find the minimum or maximum element of the input array |
| jq 'max' | Find the minimum or maximum element of the input array |
| jq 'min_by(path_exp)' | Find the minimum or maximum element of the input array |
| jq 'max_by(path_exp)' | Find the minimum or maximum element of the input array |
| jq 'unique' | The unique function takes as input an array and produces an array of the same elements, in sort |
| jq 'unique_by(path_exp)' | The unique function takes as input an array and produces an array of the same elements, in sort |
| jq 'reverse' | This function reverses an array |
| jq 'contains(element)' | The filter contains(b) will produce true if b is completely contained within the input |
| jq 'indices(s)' | Outputs an array containing the indices in . where s occurs. The input may be an array |
| jq 'index(s)' | Outputs the index of the first (index) or last (rindex) occurrence of s in the input |
| jq 'rindex(s)' | Outputs the index of the first (index) or last (rindex) occurrence of s in the input |
| jq 'inside' | The filter inside(b) will produce true if the input is completely contained within b |
| jq 'startswith(str)' | Outputs true if |
| jq 'endswith(str)' | Outputs true if |
| jq 'combinations' | Outputs all combinations of the elements of the arrays in the input array |
| jq 'combinations(n)' | Outputs all combinations of the elements of the arrays in the input array |
| jq 'ltrimstr(str)' | Outputs its input with the given prefix string removed, if it starts with it |
| jq 'rtrimstr(str)' | Outputs its input with the given suffix string removed, if it ends with it |
| jq 'trimstr(str)' | Outputs its input with the given string removed at both ends, if it starts or ends with it |
| jq 'trim' | trim trims both leading and trailing whitespace |
| jq 'ltrim' | trim trims both leading and trailing whitespace |
| jq 'rtrim' | trim trims both leading and trailing whitespace |
| jq 'explode' | Converts an input string into an array of the string's codepoint numbers |
| jq 'implode' | The inverse of explode |
| jq 'split(str)' | Splits an input string on the separator argument |
| jq 'join(str)' | Joins the array of elements given as input, using the argument as separator |
| jq 'ascii_downcase' | Emit a copy of the input string with its alphabetic characters (a-z and A-Z) converted to the s |
| jq 'ascii_upcase' | Emit a copy of the input string with its alphabetic characters (a-z and A-Z) converted to the s |
| jq 'while(cond; update)' | The while(cond; update) function allows you to repeatedly apply an update to . until cond |
| jq 'repeat(exp)' | The repeat(exp) function allows you to repeatedly apply expression exp to . until an error |
| jq 'until(cond; next)' | The until(cond; next) function allows you to repeatedly apply the expression next, initially |
| jq 'recurse(f)' | The recurse(f) function allows you to search through a recursive structure, and extract interes |
| jq 'recurse' | The recurse(f) function allows you to search through a recursive structure, and extract interes |
| jq 'recurse(f; condition)' | The recurse(f) function allows you to search through a recursive structure, and extract interes |
| jq 'walk(f)' | The walk(f) function applies f recursively to every component of the input entity |
| jq 'have_literal_numbers' | This builtin returns true if jq's build configuration includes support for preservation of inpu |
| jq 'have_decnum' | This builtin returns true if jq was built with "decnum", which is the current literal number pr |
| jq '$JQ_BUILD_CONFIGURATION' | This builtin binding shows the jq executable's build configuration |
| jq '$ENV' | $ENV is an object representing the environment variables as set when the jq program started |
| jq 'env' | $ENV is an object representing the environment variables as set when the jq program started |
| jq 'transpose' | Transpose a possibly jagged matrix (an array of arrays) |
| jq 'bsearch(x)' | bsearch(x) conducts a binary search for x in the input array |
| jq '\(exp)' | String interpolation |
| jq 'Convert to/from JSON' | The tojson and fromjson builtins dump values as JSON texts or parse JSON texts into values, res |
| jq 'SQL-Style Operators' | jq provides a few SQL-style operators |
| jq 'builtins' | Returns a list of all builtin functions in the format name/arity |
| Shortcut | Action |
|---|---|
| jq '==' | The expression 'a == b' will produce 'true' if the results of evaluating a and b are equal (tha |
| jq '!=' | The expression 'a == b' will produce 'true' if the results of evaluating a and b are equal (tha |
| jq 'if-then-else-end' | if A then B else C end will act the same as B if A produces a value other than false or null, b |
| jq '>' | The comparison operators >, >=, <=, < return whether their left argument is greater than, great |
| jq '>=' | The comparison operators >, >=, <=, < return whether their left argument is greater than, great |
| jq '<=' | The comparison operators >, >=, <=, < return whether their left argument is greater than, great |
| jq '<' | The comparison operators >, >=, <=, < return whether their left argument is greater than, great |
| jq 'and' | jq supports the normal Boolean operators and, or, not |
| jq 'or' | jq supports the normal Boolean operators and, or, not |
| jq 'not' | jq supports the normal Boolean operators and, or, not |
| jq '//' | Alternative operator |
| jq 'try-catch' | Errors can be caught by using try EXP catch EXP |
| jq '?' | Error Suppression / Optional Operator |
| Shortcut | Action |
|---|---|
| jq 'test(val)' | Like match, but does not return match objects, only true or false for whether or not the regex |
| jq 'test(regex; flags)' | Like match, but does not return match objects, only true or false for whether or not the regex |
| jq 'match(val)' | match outputs an object for each match it finds |
| jq 'match(regex; flags)' | match outputs an object for each match it finds |
| jq 'capture(val)' | Collects the named captures in a JSON object, with the name of each capture as the key |
| jq 'capture(regex; flags)' | Collects the named captures in a JSON object, with the name of each capture as the key |
| jq 'scan(regex)' | Emit a stream of the non-overlapping substrings of the input that match the regex in accordance |
| jq 'scan(regex; flags)' | Emit a stream of the non-overlapping substrings of the input that match the regex in accordance |
| jq 'split(regex; flags)' | Splits an input string on each regex match |
| jq 'splits(regex)' | These provide the same results as their split counterparts, but as a stream instead of an array |
| jq 'splits(regex; flags)' | These provide the same results as their split counterparts, but as a stream instead of an array |
| jq 'sub(regex; tostring)' | Emit the string obtained by replacing the first match of regex in the input string with tostrin |
| jq 'sub(regex; tostring; flags)' | Emit the string obtained by replacing the first match of regex in the input string with tostrin |
| jq 'gsub(regex; tostring)' | gsub is like sub but all the non-overlapping occurrences of the regex are replaced by tostring |
| jq 'gsub(regex; tostring; flags)' | gsub is like sub but all the non-overlapping occurrences of the regex are replaced by tostring |
| Shortcut | Action |
|---|---|
| jq '... as $identifier | ...' | Variable / Symbolic Binding Operator |
| jq '?//' | Destructuring Alternative Operator |
| jq 'isempty(exp)' | Returns true if exp produces no outputs, false otherwise |
| jq 'limit(n; expr)' | The limit function extracts up to n outputs from expr |
| jq 'skip(n; expr)' | The skip function skips the first n outputs from expr |
| jq 'first(expr)' | The first(expr) and last(expr) functions extract the first and last values from expr, respectiv |
| jq 'last(expr)' | The first(expr) and last(expr) functions extract the first and last values from expr, respectiv |
| jq 'nth(n; expr)' | The first(expr) and last(expr) functions extract the first and last values from expr, respectiv |
| jq 'first' | The first and last functions extract the first and last values from any array |
| jq 'last' | The first and last functions extract the first and last values from any array |
| jq 'nth(n)' | The first and last functions extract the first and last values from any array |
| jq 'reduce' | The reduce syntax allows you to combine all of the results of an expression by accumulating |
| jq 'foreach' | The foreach syntax is similar to reduce, but intended to allow the construction of limit and re |
| Shortcut | Action |
|---|---|
| jq '|=' | Update-assignment |
| jq '+=' | Arithmetic update-assignment |
| jq '-=' | Arithmetic update-assignment |
| jq '*=' | Arithmetic update-assignment |
| jq '/=' | Arithmetic update-assignment |
| jq '%=' | Arithmetic update-assignment |
| jq '//=' | Arithmetic update-assignment |
| jq '=' | Plain assignment |
| Shortcut | Action |
|---|---|
| jq 'input' | Outputs one new input |
| jq 'inputs' | Outputs all remaining inputs, one by one |
| jq 'debug' | These two filters are like |
| jq 'debug(msgs)' | These two filters are like |
| jq 'stderr' | Prints its input in raw and compact mode to stderr with no additional decoration, not even a ne |
| jq 'input_filename' | Returns the name of the file whose input is currently being filtered |
| jq 'input_line_number' | Returns the line number of the input currently being filtered |
| Shortcut | Action |
|---|---|
| jq 'truncate_stream(stream_expression)' | Consumes a number as input and truncates the corresponding number of path elements from the lef |
| jq 'fromstream(stream_expression)' | Outputs values corresponding to the stream expression's outputs |
| jq 'tostream' | The tostream builtin outputs the streamed form of its input |
| Shortcut | Action |
|---|---|
| jq 'include RelativePathString [<metadata>];' | Imports a module found at the given path relative to a directory in a search path as if it were |
| jq 'module <metadata>;' | This directive is entirely optional |
| jq 'modulemeta' | Takes a module name as input and outputs the module's metadata as an object, with the module's |
jq '.' pretty-prints the input, which is the most common invocation of all. jq '.foo' reads a key and jq '.foo.bar' a nested one; jq '.[]' iterates an array or an object's values, producing a stream, and jq '.[]?' does the same without erroring on non-iterables. Filters are chained with jq '|', so .items[] | .name lists every item's name. jq '..' recurses through every value at any depth, which combined with a filter finds a key wherever it hides. jq 'keys' and jq 'length' answer "what is in here" for an unfamiliar document.
jq 'map(f)' applies a filter to each array element and collects the results; jq '[]' and jq '{}' build arrays and objects from a stream, so [.[] | .id] collects IDs and {name, id} picks two fields. jq 'del(path_expression)' removes keys, jq 'has(key)' tests for one, and jq '//' supplies a default when a value is null or missing. jq 'if-then-else-end' branches, and jq '|=' updates in place: .price |= . * 1.1 changes a field without rebuilding the object.
jq 'test(val)' matches a regex and jq 'gsub(regex; tostring)' replaces every match; both accept flags such as "i". jq 'reduce' folds a stream into one value — reduce .[] as $x (0; . + $x.amount) sums a field — and jq '... as $identifier | ...' binds a value to a variable for reuse later in the pipeline. jq 'limit(n; expr)' and jq 'first(expr)' take the first results of a stream. jq 'inputs' reads all remaining input documents, which with -n lets one program aggregate across many files or a newline-delimited log. jq 'try-catch' turns an error into a value instead of aborting the run.
Add the -r flag to the command line: jq -r '.name' prints the value without JSON quoting, which scripts usually want.
Use select inside an iteration: .[] | select(.status == "active"). Wrap it in [ ] to collect the matches back into an array.
jq -n '[inputs]' file1 file2 collects every input document into one array; -s (slurp) is the older equivalent.
The input at that point is not an object — often an array. Iterate first with .[] or index a position with .[0].
Open your assistant with this page preloaded as the source — great for follow-up questions like "which of these work in other apps?"