Install

npm i -g jsonzen

or pnpm add -g jsonzen · yarn global add jsonzen · bun add -g jsonzen · or npx jsonzen <command> for one-off runs

Why

Every JSON tool you'd otherwise tab over to a web app for — format, diff, JSONPath query, JWT decode, JSON ↔ YAML/CSV/TypeScript — wrapped in one binary that reads stdin, writes stdout, exits with Unix codes. Zero network calls. Zero telemetry. MIT.

Powered by @jsonzen/core, the same engine behind jsonzen.dev.

Commands

format

Pretty-print JSON with line-accurate errors.

--indent · --sort

minify

Strip whitespace. Reports bytes saved on stderr.

--quiet

validate

Validate JSON against a JSON Schema (Ajv). Exits 3 on failure.

--mode · --strict

diff

Semantic diff of two documents. Exits non-zero if they differ.

--array-mode

equal

Structural equality. Exits 0/3 with the first divergence path.

—

jq / jp

JMESPath (jq) or JSONPath (jp) queries. Single-match unwrap.

--raw

jwt

Decode header, payload, and claims. No signature verification.

--header · --payload

flatten

Flat dot-paths ↔ nested JSON.

--unflatten · --array-mode

mock

Generate realistic sample JSON from a JSON Schema.

--seed · --max-depth

to-yaml / from-yaml

JSON ↔ YAML.

--indent · --sort-keys

to-csv / from-csv

JSON ↔ CSV. RFC 4180 quoting.

--delimiter · --newline

to-ts · to-zod

JSON sample → TypeScript types or Zod schema.

--top-level-name

to-pydantic

JSON sample → Pydantic v2 model.

--optional-syntax

to-schema

JSON sample → JSON Schema (Draft 2020-12 or 07).

--draft · --required

Help

Per-command help with examples.

jsonzen <cmd> --help

Every command reads from stdin, a file argument, or -, and writes to stdout or --output <file>. Compose with pipes the way you'd expect.

Quick start

Format a JSON document. Exits 0 on success, non-zero on parse failure.

$ echo '{"port":8080,"host":"localhost"}' | jsonzen format --indent 2
{
  "port": 8080,
  "host": "localhost"
}

Examples

$ jsonzen format api.json --sort --output api.json

--sort sorts object keys alphabetically. --output writes back to the same file (atomic — the original is replaced only after the new content is fully written).

$ curl -s https://api.example.com/users \
    | jsonzen jp '$.users[*].email'
[
  "[email protected]",
  "[email protected]"
]

Use jq instead of jp for JMESPath syntax. A single-match result is unwrapped automatically; multi-match results stay as an array.

$ jsonzen validate config.json schema.json --mode all-errors
$ echo $?
0
$ jsonzen validate bad.json schema.json
/port: must be integer
/host: must be string
$ echo $?
3

Exit code 3 means "valid JSON, but schema rejected it". Exit code 2 means input was unparseable. 0 means valid.

$ cat users.csv
name,age
alice,30
bob,27

$ jsonzen from-csv users.csv
[
  { "name": "alice", "age": 30 },
  { "name": "bob", "age": 27 }
]

$ jsonzen from-csv users.csv | jsonzen to-csv --delimiter ';'
name;age
alice;30
bob;27

$ echo '{"name":"alice","roles":["admin","editor"]}' \
    | jsonzen to-ts --top-level-name User
export interface User {
  name: string;
  roles: string[];
}

Use to-zod for a Zod schema, to-pydantic for a Pydantic v2 model, or to-schema to infer a JSON Schema (Draft 2020-12 or 07).

Design rules

Pure stdin / stdout. Every command reads from stdin, a file argument, or -, and writes to stdout or a file. Composes with |, <, > the way Unix tools should.

Unix exit codes. 0 for success, 2 for input errors (bad JSON, missing file), 3 for predicate failures (validate / equal / diff non-zero result). Anything else is a bug.

Zero network calls. The binary never phones home. No auto-update checks, no analytics, no remote schema fetches. Your data never leaves your machine.

Enforced by an ESLint rule set with complexity ≤ 8, no any, no console.log, 95 % line and branch coverage on every file, and JSDoc on every public export. See CONTRIBUTING.md.

Versioning

Semver. The current major is 1. Breaking changes to flag names or exit-code meanings only land on a major bump.

Contributing

See CONTRIBUTING.md. pnpm validate must be green before any PR (format + lint + typecheck + 95% coverage + build + binary version smoke).

License

MIT © JSONZen.