Basic Usage¶

Input Sources¶

jpx can read JSON from multiple sources:

Standard Input (stdin)¶

echo '{"name": "Alice"}' | jpx 'name'
# "Alice"

cat data.json | jpx 'users[*].name'
curl -s https://api.example.com/data | jpx 'results[0]'

File Input¶

# Trailing argument (jq-style)
jpx 'users[*].name' data.json

# Explicit flag
jpx 'users[*].name' -f data.json
jpx --file users.json 'length(@)'

When the last positional argument is an existing file, jpx automatically uses it as input. The -f flag is still supported for explicitness or when the file doesn't exist yet.

Null Input¶

Use -n to start with null (useful for functions that don't need input):

jpx -n 'now()'
# 1705312200

jpx -n 'uuid()'
# "550e8400-e29b-41d4-a716-446655440000"

jpx -n 'range(`1`, `5`)'
# [1, 2, 3, 4]

Output Options¶

Pretty Printing (default)¶

By default, jpx pretty-prints JSON output with colors:

echo '{"a":1,"b":2}' | jpx '@'

Output:

{
  "a": 1,
  "b": 2
}

Compact Output¶

Use -c for single-line output:

echo '{"a":1,"b":2}' | jpx -c '@'

Output:

{"a":1,"b":2}

Raw Strings¶

Use -r to output strings without quotes:

echo '{"msg": "hello"}' | jpx -r 'msg'

Output:

hello

Output to File¶

Write results to a file:

jpx 'users[*].email' -f data.json -o emails.json
# (writes to emails.json)

Slurp Mode¶

Read multiple JSON objects into an array:

echo '{"a":1}
{"b":2}
{"c":3}' | jpx -s 'length(@)'

Output:

Expression as Positional Argument¶

The expression can be the first positional argument, with an optional trailing file:

jpx 'users[*].name' data.json
jpx 'users[*].name' -f data.json

Or use -e / --expression:

jpx -e 'users[*].name' -f data.json

Chaining Expressions¶

Three ways to chain transformations:

# 1. Pipes within a single expression (most common)
jpx 'users | [*].name | sort(@)' -f data.json

# 2. Multiple positional arguments
jpx 'users' '[*].name' 'sort(@)' -f data.json

# 3. Multiple -e flags
jpx -e 'users' -e '[*].name' -e 'sort(@)' -f data.json

All three are equivalent - each expression receives the output of the previous one.

Verbose Mode¶

See expression details and timing:

echo '{"x": 1}' | jpx -v 'x'

Output:

Input: object (1 keys)

[1] Expression: x
[1] Result: number (1)
[1] Time: 0.040ms

Total time: 0.214ms
1

Quiet Mode¶

Suppress errors and warnings:

jpx -q 'invalid[' -f data.json
# (no error output, exits with non-zero status)

Color Control¶

Control colorized output:

jpx --color=always 'name' -f data.json  # Force colors
jpx --color=never 'name' -f data.json   # No colors
jpx --color=auto 'name' -f data.json    # Auto-detect (default)