# jsoncsv Commands: Expand, Restore, and Convert JSON from the Command Line

> Master jsoncsv commands to expand, restore, and convert JSON to CSV or Excel directly from your command line. Effortlessly manage nested JSON structures with this powerful Python utility.

- Repository: [alingse/jsoncsv](https://github.com/alingse/jsoncsv)
- Tags: tutorial
- Published: 2026-02-24

---

**The jsoncsv Python package provides two main command-line utilities—`jsoncsv` for flattening and restoring nested JSON structures, and `mkexcel` for converting JSON streams to CSV or Excel formats.**

The `alingse/jsoncsv` repository delivers a lightweight toolkit for JSON data transformation directly from your shell. Understanding these core jsoncsv commands enables data engineers to flatten complex hierarchies and export to spreadsheets without writing custom conversion scripts.

## Overview of Main jsoncsv Commands

The package registers two console scripts via entry points defined in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml) (lines 44-47). These wrap the underlying Python library in a Click-based CLI for seamless shell integration.

### The `jsoncsv` Command (Expand and Restore)

Implemented in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py) (lines 24-55), this command handles bidirectional transformation of JSON documents. It imports conversion logic from [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py) to either flatten nested objects or restore them to original hierarchies.

**Key capabilities:**
- **Expand mode** (`-e`, `--expand`): Flattens nested structures using dot notation (default separator `.`)
- **Restore mode** (`-r`, `--restore`): Rebuilds original JSON from flattened key-value maps
- **Safe encoding** (`--safe`): Handles keys containing the separator character to prevent collision
- **Array handling** (`--array`): Configures processing of JSON arrays during expansion

### The `mkexcel` Command (CSV and XLS Export)

Defined in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py) (lines 55-94), this command streams JSON input into spreadsheet formats. It delegates to dumper classes in [`jsoncsv/dumptool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/dumptool.py) for format-specific output generation.

**Key capabilities:**
- **Format selection** (`-t`, `--type`): Specify `csv` or `xls` output format
- **Header sorting** (`-s`, `--sort`): Alphabetize column headers in the output
- **Row inference** (`--row`): Pre-read specified number of rows to determine column ordering

## Technical Implementation of jsoncsv Commands

### How `jsoncsv` Transforms JSON Structures

When invoked with `--expand`, the command calls `convert_json()` from [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py), which executes the `expand()` function (lines 93-124). This implementation walks the JSON tree using `gen_leaf` to generate flattened keys with configurable separators. The `restore()` function reverses this operation by splitting keys and rebuilding nested structures via `from_leaf`, supporting safe-key decoding when the `--safe` flag is used.

### How `mkexcel` Generates Spreadsheets

The command instantiates either `DumpCSV` or `DumpXLS` classes from [`jsoncsv/dumptool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/dumptool.py) based on the `--type` parameter. It processes JSON streams to build two-dimensional tables mapping headers to values, then writes either text-based CSV or binary XLS workbooks to the specified output destination.

## Command-Line Usage Examples

### Flattening Nested JSON with `jsoncsv`

```bash

# Expand a JSON file using default dot separator

jsoncsv -e input.json > flat.json

```

```bash

# Use custom separator with safe key encoding for complex keys

jsoncsv -e --sep '/' --safe input.json > flat_safe.json

```

### Restoring Original Hierarchy

```bash

# Rebuild nested structure from flattened file

jsoncsv -r flat.json > restored.json

```

### Converting to CSV and Excel with `mkexcel`

```bash

# Convert JSON stream to CSV

mkexcel -t csv input.json output.csv

```

```bash

# Create Excel file with sorted headers, pre-reading 2 rows for inference

mkexcel -t xls -s --row 2 input.json output.xls

```

## Summary

- **Two primary commands**: `jsoncsv` for structural transformations (expand/restore) and `mkexcel` for format conversion (CSV/XLS)
- **Entry point registration**: Defined in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml) as `jsoncsv.main:jsoncsv` and `jsoncsv.main:mkexcel`
- **Core implementation**: [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py) handles JSON tree manipulation; [`jsoncsv/dumptool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/dumptool.py) handles spreadsheet generation
- **CLI framework**: Built on Click with support for stdin/stdout streaming, custom separators, and safe-key encoding

## Frequently Asked Questions

### What is the difference between the `jsoncsv` and `mkexcel` commands?

The `jsoncsv` command modifies JSON structure by expanding nested objects into flat key-value pairs or restoring flattened documents back to hierarchies, while `mkexcel` converts JSON into tabular spreadsheet formats without altering the internal data structure.

### How does jsoncsv handle keys containing the separator character?

Use the `--safe` flag when expanding to encode keys that contain the separator (default `.`), then use the same flag during restoration to decode them properly. This prevents the tool from interpreting embedded dots as hierarchy delimiters.

### Can jsoncsv process JSON arrays for Excel conversion?

Yes, the `mkexcel` command handles JSON streams containing arrays or objects, flattening them into rows. Use the `--row` parameter to pre-read rows for improved header inference when processing heterogeneous data structures.

### Where are the command-line entry points defined in the source code?

The console scripts are registered in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml) under `[project.scripts]`, mapping the `jsoncsv` command to `jsoncsv.main:jsoncsv` and `mkexcel` to `jsoncsv.main:mkexcel`. The Click command definitions and argument parsing logic reside in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py).