jsonzen

JSON tools in your terminal.
Format · validate · diff · query · convert — without leaving the shell.

---

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

Format a file in place

$ 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).

Pipe stdin → JSONPath query → stdout

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

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

Validate a config against a JSON Schema

$ 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.

Convert CSV ↔ JSON

$ 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

Generate TypeScript types from a JSON sample

$ 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.