jq

name	jq
description	Use when working with the jq command-line JSON processor — filters, builtins, operators, path expressions, assignments, variables, functions, regex, format strings, dates, modules, invocation flags, and exit codes. Triggers on all jq-related topics: filters, programs, queries, the manual, builtins, regex, modules, reduce/foreach, select/walk/recurse/map, CLI flags (--arg, --argjson, --null-input, --raw-output, --compact-output, --stream, --exit-status), format strings (@base64, @csv, @sh, @uri), tojson/fromjson, date functions, $ENV/env, path functions (getpath, setpath, del, paths), sort/group_by, sub/gsub/test/match, with_entries/map_values, modulemeta/import, input/inputs, operators (//, destructuring), control flow (label, break, try, catch), and SQL-style builtins (INDEX, JOIN).
user-invocable	true

jq — Command-line JSON Processor In-Depth Reference

Comprehensive reference for the jq language and CLI — filters, builtin functions, operators, path expressions, assignments, variables, functions, regex, format strings, dates, modules, and invocation. Covers jq 1.7. Source: https://jqlang.github.io/jq/manual/.

Data Flow

Input (stdin / files / --null-input)
  → JSON parser (stream of whitespace-separated values)
    → filter program (pipeline of filters, one input → zero or more outputs)
      → output formatter (--compact-output, --raw-output, --tab, --indent, --sort-keys)
        → stdout (newline-separated JSON texts)

A jq program is a single filter expression. Every filter takes one input and produces zero or more outputs. Filters compose with | (pipe), , (comma), and operators. Multiple outputs from one stage are fed one-by-one into the next — this is the generator model at the heart of jq.

Sub-Resources

Load the reference that matches your task. When in doubt, load multiple references.

Keywords	Reference
invocation, command line, flags, options, --null-input, -n, --raw-input, -R, --slurp, -s, --compact-output, -c, --raw-output, -r, --raw-output0, --join-output, -j, --ascii-output, -a, --sort-keys, -S, --color-output, -C, --monochrome-output, -M, --tab, --indent, --unbuffered, --stream, --stream-errors, --seq, --from-file, -f, -L, --library-path, --arg, --argjson, --slurpfile, --rawfile, --args, --jsonargs, --exit-status, -e, --binary, -b, --version, -V, --build-configuration, --help, -h, --run-tests, --, exit status, exit code, JQ_COLORS, NO_COLOR, $ENV, env, $ARGS, shell quoting, stdin, files	references/cli.md
filter, identity, ., .foo, .foo.bar, .foo?, optional, object index, .["foo"], array index, .[0], negative index, slice, .[2:4], .[:3], .[-2:], value iterator, .[], .[]?, comma, pipe,	, parenthesis, recursive descent, .., basic filter
type, value, number, string, boolean, null, array, object, array construction, [], object construction, {}, shortcut syntax, {user, title}, key expression, variable key, {$foo}, IEEE754, double precision, number literal, precision	references/types.md
addition, +, subtraction, -, multiplication, *, division, /, modulo, %, abs, length, utf8bytelength, arithmetic, array concatenation, string concatenation, object merge, null addition, comparison, ==, !=, >, >=, <=, <, and, or, not, truthiness, alternative operator, //, default value, sort order	references/operators.md
builtin, function, keys, keys_unsorted, has, in, map, map_values, pick, select, arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars, empty, error, halt, halt_error, $loc, paths, add, any, all, flatten, range, floor, sqrt, tonumber, tostring, type, infinite, nan, isnan, isinfinite, isfinite, isnormal, sort, sort_by, group_by, min, max, min_by, max_by, unique, unique_by, reverse, contains, indices, index, rindex, inside, startswith, endswith, combinations, ltrimstr, rtrimstr, explode, implode, split, join, ascii_downcase, ascii_upcase, while, repeat, until, recurse, walk, transpose, bsearch, builtins, getpath, setpath, delpaths, to_entries, from_entries, with_entries, path, del	references/builtins.md
conditional, if, then, else, elif, end, try, catch, ?, error suppression, optional operator, reduce, foreach, label, break, breaking out, control structure, generators, iterator, tail call, recursion	references/control.md
variable, binding, as, $name, destructuring, pattern, ?//, alternative, def, function definition, function argument, scoping, lexical scope, filter argument, callback, value argument, addvalue, isempty, limit, skip, first, last, nth

Quick Guide

• How do I invoke jq and what do the flags do? → references/cli.md
• How do I write a basic filter (., .foo, .[], |)? → references/filters.md
• What types does jq support and how do I construct arrays/objects? → references/types.md
• How do arithmetic, comparison, and boolean operators work? → references/operators.md
• What builtin functions are available (map, select, add, sort, etc.)? → references/builtins.md
• How do if/try/reduce/foreach and label/break work? → references/control.md
• How do I bind variables (as $x) and define functions (def)? → references/variables-functions.md
• How do path expressions and assignment operators (=, |=, +=) work? → references/paths-assignment.md
• What string functions exist (split, join, interpolation, etc.)? → references/strings.md
• How do jq regular expressions work (test, match, sub, gsub, flags)? → references/regex.md
• What are the @foo format strings and how do they escape? → references/formats.md
• How do I parse and format dates in jq? → references/dates.md
• How do modules, I/O builtins, and SQL-style operators work? → references/modules.md
• How do I pass variables from the command line (--arg, --argjson)? → references/cli.md
• What exit codes does jq use? → references/cli.md

Cross-Project References

• For carapace-specific jq integration (the jq completer in completers/common/jq_completer/), see the carapace-dev skill → references/action.md. The completer itself only covers CLI flags and file/directory arguments — it does not complete the jq filter language.
• For shell quoting rules that affect how jq programs are passed on the command line, see the bash, zsh, or fish skills as appropriate for the target shell.