charmbracelet/crush/jq

jq — Built-in JSON Processor

Crush ships a built-in jq command (via github.com/itchyny/gojq) available in the bash tool. No external binary is required.

Supported Flags

File arguments after the filter are also supported: jq '.foo' file.json.

Differences from Standard jq

The built-in uses gojq, which is a pure-Go jq implementation. Key differences:

• No object key ordering — keys are sorted by default; keys_unsorted

and -S are unavailable.

• Arbitrary-precision integers — large integers keep full precision

(addition, subtraction, multiplication, modulo, division when divisible).

• String indexing — "abcde"[2] returns "c".
• Not supported — --ascii-output, --seq, --stream,

--stream-errors, -f/--from-file, --slurpfile, --rawfile, --args, --jsonargs, input_line_number, $__loc__, some regex features (backreferences, look-around).

• YAML — gojq supports --yaml-input/--yaml-output but the

built-in does not currently expose these flags.

Common Patterns

Extract a field:

echo '{"name":"crush"}' | jq '.name'

Filter an array:

echo '[1,2,3,4,5]' | jq '[.[] | select(. > 3)]'

Reshape objects:

echo '{"first":"Ada","last":"Lovelace"}' | jq '{full: (.first + " " + .last)}'

Use variables:

echo '{}' | jq --arg host localhost --argjson port 8080 '{host: $host, port: $port}'

Slurp multiple JSON values:

echo '{"a":1}{"b":2}' | jq -s '.'

Compact output for piping:

echo '{"a":1}' | jq -c '.a += 1'

Raw string output:

echo '["one","two","three"]' | jq -r '.[]'

Process a file:

jq '.dependencies | keys' package.json

Null input for constructing JSON:

jq -n --arg msg hello '{"message": $msg}'

Tips

• Pipe jq output to other commands: jq -r '.url' data.json | xargs curl
• Chain filters with | inside the expression, not shell pipes.
• Use try to suppress errors on missing keys: jq 'try .foo.bar'
• Use // "default" for fallback values: jq '.name // "unknown"'
• Use @csv, @tsv, @base64, @html, @uri for format strings.