Command-line reference.
jb is a command-line tool for JSON discovery and search, built for AI agents and humans alike. This page documents installation, the in-built help system, and every subcommand. For the desktop app, see the GUI docs.
01Install
Pick the channel that matches your workflow. The CLI binary is also bundled inside the GUI app, so installing one gets you both.
Windows · winget
PS> winget install jsonbolt # Adds `jb` to PATH and registers the .json file association.
Windows · installer
Download jsonbolt-1.4.2-x64.msi from the downloads page. The installer is signed and notarized.
macOS · private beta
$ brew tap jsonbolt/beta $ brew install --cask jsonbolt
Linux · private beta
$ curl -fsSL https://get.jsonbolt.dev | sh # Or grab the .deb / .rpm / .AppImage from GitHub Releases.
02Get help
Run jb help to print the top-level reference: usage syntax, the list of subcommands, and the path forms accepted on input. To see the help for a specific subcommand, pass its name to jb help, or run the subcommand with --help.
$ jb help # top-level reference $ jb help search # detailed help for one subcommand $ jb search --help # same as `jb help search` $ jb search -h # short form of --help
The help output is the canonical reference. The pages here are derived from it, so if anything ever disagrees, trust jb help.
03Explore a file
When you're handed a JSON file you've never seen before, four subcommands answer the basic structural questions. Running them in order on a new document is a good way to get a feel for it before writing more specific queries.
$ jb schema analytics_2026.json # tree shape with type info $ jb paths analytics_2026.json # every path in the document, one per line $ jb keys analytics_2026.json # every distinct key name, deduped $ jb get .users[0] analytics_2026.json # the value at a specific path
schema answers what's in the document. paths answers where can I look. keys answers what are things called. get extracts a specific value once you know the path. To search for values that match a query, see jb search.
Throughout these examples, <file> can be a path on disk, - to read from stdin, or a glob pattern that matches several files. See Files & globs.
04jb search
Searches a JSON document for values, keys, or properties that match a query. By default, the search term is matched against string values only. Pass --all-types to also match numbers, booleans, and null; --keys-only or --values-only to scope the match; or use --key and --value together to query keys and values separately (covered below).
$ jb search "alice" data.json $ jb search --keys-only -r "^user_" data.json $ jb search --key email --value "@acme" users.json $ jb search --where '.age > 30 && .role == "admin"' users.json $ jb search --exists .id orders.json # exit 0 if .id is present, 1 if absent $ jb search --ai "errors" logs.json # bounded jsonl output, safe for piping into LLMs
Aliases
Two short aliases cover patterns that come up often:
jb find <value>is equivalent tojb search --all-types --values-only --emit assignment. It prints gron-style assignments for matched values of any type.jb extract <path-pattern>is equivalent tojb search --path PAT --emit value --values-only. It prints just the values at paths matching the pattern.
$ jb find 42 data.json $ jb extract '.users[*].email' data.json
Search flag reference
| Flag | Effect |
|---|---|
-r, --regex | Treat the term as a regex pattern |
-S, --case-sensitive | Match case exactly (default: case-insensitive) |
--keys-only | Match keys only |
--values-only | Match values only |
--key <KQ> | KV-mode key query; pair with --value or use alone |
--value <VQ> | KV-mode value query; both must match on the same property when paired |
--all-types | Match values of any type (default: strings only) |
-t, --type <T> | Filter by JSON type: string · number · boolean · null · object · array |
-p, --path <PATTERN> | Restrict search to paths matching PATTERN ([*], [], .* wildcards) |
-e, --where <EXPR> | Filter objects by predicate — see Where predicates |
--exists <PATH> | Exit 0 if PATH exists in the document, 1 if not |
--missing <PATH> | Exit 0 if PATH is absent, 1 if present |
--emit <MODE> | path (default) · value · assignment · object · parent |
-n, --limit <N> | Stop after N unique paths (early-exit). Alias: --max-results |
-1, --first | Alias for --limit 1 |
-c, --count | Print only the total match count |
--max-value-bytes <N> | Truncate value previews longer than N bytes |
--max-output <N> | Hard cap on total stdout bytes (suffix K/M/G allowed) |
--ai | LLM-friendly defaults: --format jsonl --envelope --max-output 1M --max-value-bytes 256 |
--envelope | Wrap each match in {path, preview, value} for jsonl/json formats |
--raw | Strip surrounding quotes from string scalars in plain output |
-f, --format <fmt> | plain (default) · jsonl · json |
--color <when> | auto (default) · always · never |
05jb get
Extracts the JSON value at <path> from a document. Output is pretty-printed by default. Pass --minify for compact, single-line output suitable for piping into other tools.
$ jb get .users[0].email data.json $ jb get --minify .users[0] data.json
Six path syntaxes are accepted on input. See Path forms.
06jb schema
Prints the structural shape of a JSON document — keys, types, and nesting — without the values. shape is an alias for schema. paths is an alias for schema --paths-only and prints only the list of paths.
$ jb schema config.json # tree shape $ jb shape config.json # alias for schema $ jb paths config.json # alias for `schema --paths-only`
Array indices collapse to [*] by default. A 1 GB list of N items shows ~30 paths instead of 30·N — handy when you're triaging an unfamiliar file. Pass --no-collapse when you need a per-index breakdown.
Schema flag reference
| Flag | Effect |
|---|---|
--format <fmt> | text (default) · jsonl · json |
--no-collapse | Keep distinct entries per array index (default collapses to [*]) |
--paths-only | Emit only path strings, one per line |
--examples <N> | Keep up to N example values per path (default 3) |
--max-paths <N> | Hard cap on unique paths walked (default 100000) |
07jb keys
Prints every distinct key name in the document, sorted, one per line. Array indices and the synthetic root anchor are skipped — only object key names land in the output.
$ jb keys config.json $ jb keys data.json | sort -u
One flag: --max-paths <N> caps the unique paths walked (default 100000). Reach for it on pathological inputs.
08jb flatten
Flattens a JSON document into path = value assignments, one line per leaf value. The output is greppable and composes well with grep, awk, and sort. Containers (objects and arrays) are skipped by default — pass --objects-too to include lines like .users = [array].
$ jb flatten config.json $ jb flatten data.json | grep '\.email' $ jb flatten --objects-too --limit 50 huge.json
Flatten flag reference
| Flag | Effect |
|---|---|
--objects-too | Emit lines for containers too (e.g. .users = [array]) |
--max-value-bytes <N> | Truncate value bytes longer than N |
--limit <N> | Stop after N lines (early-exit) |
09Path forms
Six path syntaxes are accepted on input by jb get, --path, --exists, --missing, and any other flag that takes a path. Output paths are always printed in jq style, so the path you see in output is a path you can paste back.
| Style | Example |
|---|---|
| jq — default output | .users[0].email |
| canonical — legacy | root.users[0].email |
| JSONPath | $.users[0].email |
| lodash — numeric segments → array indices | users.0.email |
| JSON Pointer — RFC 6901 | /users/0/email |
| bracket-key | $['my key'] |
10Where predicates
The --where flag filters matches to objects whose fields satisfy a predicate. Predicates support boolean composition, comparison, string operators, regex, presence checks, and length.
$ jb search --where '.age > 30' users.json $ jb search --where '.role == "admin" || .role == "owner"' users.json $ jb search --where '.address.country == "US" && .visible' users.json $ jb search --where '.email matches /@acme\.(com|io)$/i' users.json $ jb search --where '.projects | length > 0' users.json
| Category | Operators |
|---|---|
| Connectors | && / and, || / or, ! / not, parens |
| Comparison | == != > >= < <= |
| String | contains, startsWith, endsWith |
| Presence | exists, missing |
| Length | <path> | length CMP NUMBER |
| Regex | matches /PATTERN/[flags] (flags: i m s) |
A bare path with no clause is truthy when the value at that path is neither null nor false. So --where '.visible' matches any object whose visible field is set to a truthy value.
11Common flags
Flags that appear in more than one subcommand are listed here. Per-command flags are documented in their respective sections above.
| Flag | Where | What it does |
|---|---|---|
--ai | search | LLM-friendly preset — see the Search flag reference for the expansion |
-f, --format | search | plain (default) · jsonl · json |
--color <when> | search | auto · always · never |
--envelope | search | Wrap matches in {path, preview, value} for jsonl/json |
--raw | search | Strip surrounding quotes from string scalars in plain output |
-n, --limit · -1 · -c | search | Early-exit after N · first match only · count-only |
--max-output · --max-value-bytes | search | Output ceilings; suffix K / M / G allowed on --max-output |
--minify | get | Compact single-line JSON output |
12Exit codes
| Code | Meaning |
|---|---|
0 | Match · get succeeded · --exists path present · --missing path absent |
1 | No match |
2 | Usage error |
3 | Runtime error |
4 | Path not found (get) |
13Files & globs
The trailing <file> argument is optional. When omitted, jb reads from stdin. When supplied, it can be:
- A path to a JSON file on disk.
- A literal
-to read from stdin (always uses the streaming parser). - A glob pattern such as
data/*.jsonor**/*.json.
If the glob expands to more than one file, each result is prefixed with the file path in plain output, or carries a file field in jsonl and json output.
$ kubectl get pods -o json | jb search --keys-only image - $ jb search --where '.level == "error"' 'logs/*.ndjson'
14Limits
If you run into trouble — a parse that takes longer than expected, a result that looks truncated, a query that doesn't terminate — please open an issue. Include the file size and the exact command you ran. Machine specs are useful but not required.