jsont — JSON Traverse

jsont

is a fast CLI for querying and exploring JSON/JSONL data. It replaces throwaway Python scripts and complex jq pipelines with readable, SQL-like queries and built-in data exploration commands.

jt

is a built-in alias — both commands are identical. All examples below use

jt

for brevity.

Install

bash

curl -fsSL i.jsont.sh | sh

Or with Go:

bash

go install github.com/okaris/jsont/cmd/jt@latest

Start here — pick the right command first

I want to...	Command	Notes
Find something in data	`jt file find "text"`	Always start here. 20 results, truncated, shows paths.
Understand the structure	`jt file schema`	Shows fields, types, frequencies.
Filter + display	`jt file 'where .x == "y" select .a, .b first 20' --table`	Use `first N` on large data.
Display mixed-type fields	`select substr(to_string(.field), 0, 150) as preview`	Universal pattern — never nulls.
Count per category	`jt file 'count by .field'`	Append `count` to any query — don't pipe.
Search across files	`jt *.jsonl find "text" --show-file`	Shows source filename per match.
Export	`jt file 'select ...' --csv > out.csv`	Also: `--table` , `--json` , `--raw`

Two-call pattern for any search task:

```
jt *.jsonl find "failed" --show-file
```
— see what's there, which files, which paths

jt *.jsonl 'where .message.content contains "failed" select substr(to_string(.message.content), 0, 150) as preview, .timestamp sort by .timestamp desc first 30' --table

— structured view

Reference files

For detailed behavior beyond this guide, read these as needed:

```
references/large-data-playbook.md
```
— Step-by-step for large/many files, anti-patterns, output format cheat sheet.
```
references/query-language.md
```
— Full operator precedence, all operators/functions with type behavior, edge cases.
```
references/explore-commands.md
```
— Detailed explore command output formats and options.

When to use jt

Use jt instead of writing Python/Node/jq whenever you need to:

Understand what's in a JSON/JSONL file (schema, tree, fields, stats, find)
Filter, select, sort, count, or group JSON objects
Extract fields from large JSONL log files
Search for values across deeply nested structures
Get quick stats on numeric/string fields
Pretty-print or convert between JSON formats (JSON, JSONL, CSV, table)

jt auto-detects JSON vs JSONL, handles stdin, multiple files, and malformed lines gracefully.

Minimize tool calls

The goal is one jt command, useful output, done. Avoid multi-step pipelines or piping jt through jt.

Searching for content: Use

find

first — it's one command, auto-truncates long values, and shows exactly where matches are. Don't start with

where

queries on unknown data.

bash

# GOOD: one call, clean truncated output
jt *.jsonl find "failed"

# ONLY if you need filtered/structured results after seeing what find returned:
jt data.jsonl 'where .error.message contains "failed" select .id, .error.message first 20' --table

Formatting output: Use flags, not extra commands:

bash

jt data.jsonl 'select .id, .status first 10' --table    # readable aligned table
jt data.jsonl 'select .id, .status first 10' --csv      # CSV with headers
jt data.jsonl 'select .email' --raw                      # plain strings, no quotes
jt data.jsonl 'where .error exists first 10' --json      # pretty JSON

Large data playbook

For many files or unfamiliar data: schema → find → targeted query. Each is one tool call.

bash

jt data.jsonl schema                                                        # 1. what fields exist?
jt data.jsonl find "error"                                                  # 2. where does it appear? (20 results, truncated)
jt data.jsonl 'where .error.message contains "timeout" select .id, .error.message first 20' --table  # 3. precise query

Always use

first N

with

where

on large data.

find

is already limited by default.

See

references/large-data-playbook.md

for the full guide — anti-patterns, output format cheat sheet, and common task recipes.

Explore Commands

These commands help you understand unfamiliar data fast. No query language needed.

Pretty-print (default)

bash

jt data.jsonl                    # pretty-print all objects
jt data.json                     # pretty-print single object or array
cat data.jsonl | jt              # stdin works too

schema — Infer types, frequency, and example values

bash

jt data.jsonl schema

Output shows every field path, its types, how often it appears, and sample values. Use this first when exploring unfamiliar data.

tree — Structural overview

bash

jt data.jsonl tree

Hierarchical view with box-drawing characters. Shows optional fields marked with

, array types, and mixed types with

fields — List all unique dot-paths

bash

jt data.jsonl fields

Flat sorted list, one path per line. Includes nested paths (

.error.message

) and array element paths (

.items[].name

). Useful for piping.

find — Full-text search across all values

bash

jt data.jsonl find "timeout"           # case-insensitive, returns up to 20 matches
jt data.jsonl find "timeout" 50        # return up to 50 matches
jt nested.jsonl find "error"           # searches at any nesting depth

Returns object index, dot-path where found, and the matching value. Finds things buried deep in nested structures without knowing the exact path.

stats — Statistical summary

bash

jt data.jsonl stats

Shows: total objects, distinct schema shapes, unique field count, numeric field stats (min/median/p95/p99/max), string field distributions (unique count, top values), and null/missing percentages.

head / tail / count / sample

bash

jt data.jsonl head 3             # first 3 objects (default 5)
jt data.jsonl tail 3             # last 3 objects (default 5)
jt data.jsonl count              # total number of objects
jt data.jsonl sample 10          # random sample of 10 objects

Query Language

Readable, SQL-like syntax. All clauses are optional and composable.

jt <files...> '[select FIELDS] [where CONDITION] [sort by FIELD [asc|desc]] [group by FIELD] [count [by FIELD]] [first N | last N]'

Dot-path expressions

.field                    — object field access
.field.nested             — nested access
.field[0]                 — array index
.field[0].nested          — field access after array index
.field[0].a[1].b          — chained array index + field access
.field[-1]                — last element (negative index)
.field[2:5]               — array slice
.field[]                  — iterate all array elements
.field[].nested           — nested inside each array element
..field                   — recursive descent (find at any depth)

Missing fields return

null

, never error.

select — Choose output fields

bash

jt data.jsonl 'select .id, .name, .error.message'
jt data.jsonl '.name'                                    # bare path = implicit select
jt data.jsonl 'select .id, .error.message as err'        # alias
jt data.jsonl 'select .id, .end - .start as duration'    # computed
jt data.jsonl 'select .id, .price * .quantity as total'  # arithmetic
jt data.jsonl 'select .items[0].name'                    # array index + field
jt data.jsonl 'select .message.content[0].type'          # nested array + field
jt data.jsonl 'select "\(.first) \(.last)" as name'      # string template
jt data.jsonl 'select *'                                 # all fields (default)
jt data.jsonl 'select .metadata.*'                       # wildcard

where — Filter objects

bash

# Comparison
jt data.jsonl 'where .status == "failed"'
jt data.jsonl 'where .latency_ms > 1000'
jt data.jsonl 'where .age >= 18 and .age <= 65'
jt data.jsonl 'where .message.content[0].type == "tool_use"'  # array index in where

# String operators
jt data.jsonl 'where .name contains "error"'
jt data.jsonl 'where .id starts with "run_"'
jt data.jsonl 'where .file ends with ".json"'
jt data.jsonl 'where .msg matches /time.*out/i'

# Set membership
jt data.jsonl 'where .status in ("ok", "pending")'

# Existence and type checks
jt data.jsonl 'where .error exists'
jt data.jsonl 'where .meta is null'
jt data.jsonl 'where .content is array'
jt data.jsonl 'where .content is string'

# Logical operators
jt data.jsonl 'where .status == "failed" and .latency_ms > 1000'
jt data.jsonl 'where .code == 429 or .code == 503'
jt data.jsonl 'where not .active'
jt data.jsonl 'where (.a > 1 or .b > 1) and .c == true'

# Recursive descent — search at any depth
jt data.jsonl 'where ..error contains "timeout"'

# Array contains (element)
jt data.jsonl 'where .tags contains "urgent"'

All where operators:

==

!=

>=

<=

contains

starts with

ends with

matches /regex/

in (values)

exists

is null

is <type>

and

or

not

()

sort by

bash

jt data.jsonl 'sort by .latency_ms'              # ascending (default)
jt data.jsonl 'sort by .latency_ms desc'          # descending
jt data.jsonl 'sort by .status, .latency_ms desc' # multi-field

group by

bash

jt data.jsonl 'group by .status'
# Output: {"key": "ok", "count": 100, "items": [...]}

jt data.jsonl 'select .model, count(), avg(.latency_ms) group by .model'

count / count by

bash

jt data.jsonl 'count'                             # total
jt data.jsonl 'where .status == "failed" count'   # filtered count
jt data.jsonl 'count by .model'                   # per unique value
jt data.jsonl 'count by .status sort by count desc'

first / last

bash

jt data.jsonl 'first 10'
jt data.jsonl 'where .error exists first 5'
jt data.jsonl 'last 10'
jt data.jsonl 'sort by .latency_ms desc first 20'

distinct

bash

jt data.jsonl 'distinct .status'        # unique values
jt data.jsonl 'distinct .model'

Aggregate functions

Work standalone or with

group by

bash

jt data.jsonl 'select count()'
jt data.jsonl 'select avg(.latency_ms)'
jt data.jsonl 'select min(.age), max(.age)'
jt data.jsonl 'select sum(.amount)'
jt data.jsonl 'select .model, count(), avg(.latency_ms) group by .model sort by count() desc'

Functions:

count()

sum()

avg()

min()

max()

Scalar functions

bash

jt data.jsonl 'select .name, length(.name) as len'
jt data.jsonl 'where length(.tags) > 3'
jt data.jsonl 'select lower(.email) as email'
jt data.jsonl 'select coalesce(.nickname, .name) as display'
jt data.jsonl 'select type(.content) as content_type'
jt data.jsonl 'where .msg matches /error/i select regex_extract(.msg, /error: (.+)/) as err'

Functions:

length()

lower()

upper()

trim()

type()

keys()

values()

abs()

floor()

ceil()

round()

sqrt()

pow()

coalesce()

if()

split()

join()

replace()

substr()

to_number()

to_string()

regex_extract()

regex_extract_all()

Arithmetic

Works in

select

and

where

bash

jt data.jsonl 'select .id, .price * .quantity as total'
jt data.jsonl 'where .end - .start > 1000'
jt data.jsonl 'select .id, round(.score * 100, 2) as pct'

Operators:

(also string concat),

Combined Queries — Full Pipeline

Clauses compose left to right:

bash

# Select + filter + sort + limit
jt logs.jsonl 'select .id, .model, .latency_ms where .status == "failed" sort by .latency_ms desc first 10'

# Filter + count
jt logs.jsonl 'where .error exists count'

# Count by + sort
jt logs.jsonl 'count by .model sort by count desc'

# Recursive search + select
jt logs.jsonl 'where ..error contains "timeout" select .id, .error.message'

# Group with aggregates
jt logs.jsonl 'select .model, count(), avg(.latency_ms) as avg_ms group by .model sort by count() desc'

Output Formats

jt auto-detects: pretty JSON in terminal, compact JSONL when piped. Override with flags:

Flag	Format
`--json` , `-j`	Pretty JSON
`--jsonl`	Compact JSONL (one per line)
`--compact` , `-c`	Compact JSON
`--table` , `-t`	ASCII table with headers
`--csv`	CSV with header row
`--tsv`	TSV with header row
`--raw` , `-r`	Raw strings (no JSON quotes)
`--nul` , `-0`	Null-delimited

Examples

bash

jt data.jsonl 'select .id, .status, .latency_ms first 5' --table
jt data.jsonl 'select .email' --raw | sort -u
jt data.jsonl 'where .active == true' --csv > export.csv
jt data.jsonl head 3 --json

Other output flags

bash

--show-file        # prepend source filename to each object
--show-index       # prepend object index
--flatten          # flatten nested objects to dot-path keys
--no-color         # disable color

Input

Auto-detect:
```
.json
```
(single object or array) vs
```
.jsonl
```
(newline-delimited)
JSON arrays unwrapped:
```
[{...}, {...}]
```
treated as rows automatically
Multiple files:
```
jt *.jsonl 'query'
```
— union of all files

Stdin:

cat data.jsonl | jt 'query'

cat data.jsonl | jt - 'query'

curl api | jt schema

Malformed lines: skipped by default.
```
--strict
```
to error.
```
--silent
```
to suppress warnings.

Handling mixed-type fields

Real-world JSON often has fields that are sometimes a string, sometimes an array (e.g.,

.message.content

). jt handles this:

```
contains
```
works on both strings (substring) and arrays (element match)
```
substr()
```
,
```
lower()
```
,
```
replace()
```
,
```
to_string()
```
auto-coerce non-strings to JSON — they never return null on wrong types

Use

type(.field)

to check:

where .content is string

where .content is array

bash

# Filter works regardless of content type (string or array)
jt data.jsonl 'where .message.content contains "error" first 10'

# Display mixed content as truncated string — always works
jt data.jsonl 'where .message.content contains "failed" select substr(to_string(.message.content), 0, 150) as preview, .timestamp sort by .timestamp desc first 30' --table

This pattern —

substr(to_string(.field), 0, N) as name

— is the universal way to display any field as a truncated readable string in table output, regardless of its type.

Complex Query Examples

These are real-world one-liners. Use them as templates.

Search conversation logs (Claude Code JSONL)

bash

# Find user messages containing a term, show truncated preview
jt *.jsonl 'where .type == "user" and .message.content contains "error" select substr(replace(to_string(.message.content), "\n", " "), 0, 150) as msg, .timestamp sort by .timestamp desc first 30' --table

# Filter by tool type using array index field access
jt *.jsonl 'where .message.content[0].type == "tool_use" select .message.content[0].name as tool first 20' --table

# Count tool usage by name
jt *.jsonl 'where .message.content[0].type == "tool_use" select .message.content[0].name as tool' --jsonl | jt - 'count by .tool' --table

# Count messages by type
jt *.jsonl 'count by .type'

# Find all distinct session IDs with errors
jt *.jsonl 'where .message.content contains "failed" distinct .sessionId'

# Search across files, show source file
jt *.jsonl find "timeout" --show-file

API logs / run data

bash

# Error rate by model, sorted
jt runs.jsonl 'count by .model where .status == "failed" sort by count desc' --table

# Slow requests with error details
jt runs.jsonl 'where .latency_ms > 5000 select .id, .model, .latency_ms, coalesce(.error.message, "ok") as err sort by .latency_ms desc first 20' --table

# P95 latency by model
jt runs.jsonl 'select .model, count(), avg(.latency_ms) as avg_ms, max(.latency_ms) as max_ms group by .model sort by count() desc' --table

# Export errors to CSV
jt runs.jsonl 'where .error exists select .id, .error.message, .error.code, .timestamp' --csv > errors.csv

Data inspection

bash

# What types does a field have across objects?
jt data.jsonl 'select type(.content) as t distinct .t'

# Find nulls
jt data.jsonl 'where .email is null count'

# Objects with unexpected types
jt data.jsonl 'where .age is string select .id, .age first 10'

jsont

NPX Install

Tags

SKILL.md Content

jsont — JSON Traverse

Install

Start here — pick the right command first

Reference files

When to use jt

Minimize tool calls

Large data playbook

Explore Commands

Pretty-print (default)

schema — Infer types, frequency, and example values

tree — Structural overview

fields — List all unique dot-paths

find — Full-text search across all values

stats — Statistical summary

head / tail / count / sample

Query Language

Dot-path expressions

select — Choose output fields

where — Filter objects

sort by

group by

count / count by

first / last

distinct

Aggregate functions

Scalar functions

Arithmetic

Combined Queries — Full Pipeline

Output Formats

Examples

Other output flags

Input

Handling mixed-type fields

Complex Query Examples

Search conversation logs (Claude Code JSONL)

API logs / run data

Data inspection