json-flatten (CLI)

Flatten nested JSON into dot-notation keys — and unflatten it back. The transform is lossless: flatten then unflatten returns the original. Zero dependencies.

Handy for diffing configs line-by-line, generating env vars from nested settings, flattening i18n message files, or feeding nested JSON into tabular tools.

Installs the json-flatten command. (npm package name is json-flatten-cli.)

Install

npm install -g json-flatten-cli

Or without installing:

npx json-flatten-cli config.json

Usage

json-flatten config.json              # Flatten
json-flatten flat.json --unflatten    # Rebuild nested JSON
json-flatten config.json -d /         # Use "/" as the separator
json-flatten settings.json --no-arrays
cat nested.json | json-flatten - --compact

Example

config.json:

{
  "db": { "host": "localhost", "port": 5432 },
  "features": ["auth", "billing"],
  "log": { "level": "info" }
}

json-flatten config.json:

{
  "db.host": "localhost",
  "db.port": 5432,
  "features.0": "auth",
  "features.1": "billing",
  "log.level": "info"
}

Reverse it with --unflatten and you get the original structure back — arrays included (numeric keys become array indices).

Why Flatten?

| Use case | Benefit | |---|---| | Config diffs | Flat keys diff cleanly line-by-line (great with json-diff) | | Env vars | db.host → DB_HOST is a short hop | | i18n files | home.title.welcome keys are easy to grep and sort | | Tabular export | One flat object = one CSV row | | Feature flags | Flat dotted keys map to many flag systems |

Round-Trip Guarantee

json-flatten data.json | json-flatten - --unflatten
# → structurally identical to data.json

Keys that contain the delimiter literally are backslash-escaped on flatten and restored on unflatten, so no information is lost.

Options

| Flag | Default | Description | |---|---|---| | -u, --unflatten | off | Reverse: flat keys → nested | | -d, --delimiter <d> | . | Key separator | | --max-depth <n> | ∞ | Stop flattening past this depth | | --no-arrays | off | Keep arrays intact (don't index in) | | -o, --out <file> | — | Write to a file | | --compact | off | Single-line JSON |

License

MIT

Keywords

flatten json · unflatten json · dot notation · nested json · json flattener · flat keys · json transform · config flatten · zero dependencies · cli

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.