# CLI Entry Point for jsoncsv: How the Command-Line Interface Works

> Discover the CLI entry point for jsoncsv in jsoncsv/main.py. Learn how the command-line interface works and how it's registered via pyproject.toml for easy execution.

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

---

**The CLI entry point for jsoncsv is the `jsoncsv` function located in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py), registered as a console script in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml) under the `[project.scripts]` section.**

The jsoncsv tool, maintained in the `alingse/jsoncsv` repository, provides bidirectional conversion between JSON and CSV formats through a command-line interface. Understanding the CLI entry point helps developers extend the tool, debug issues, or invoke it programmatically from other Python scripts.

## Where the CLI Entry Point Is Defined

The primary entry point resides in the `jsoncsv` function inside [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py). This function is decorated with Click commands and options to handle argument parsing.

When you install the package via pip, the executable is created through the following declaration in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml):

```toml
[project.scripts]
jsoncsv = "jsoncsv.main:jsoncsv"
mkexcel = "jsoncsv.main:mkexcel"

```

This configuration tells the package installer to generate a `jsoncsv` executable that points directly to the `jsoncsv` function in the `jsoncsv.main` module. The same file also contains a secondary entry point `mkexcel` for Excel format output.

## How the Entry Point Works Internally

The `jsoncsv` function uses the **Click** library to build the command-line interface. The workflow follows these steps:

1. **Click decorators** (`@click.command()` and `@click.option`) parse command-line flags including `--sep`, `--safe`, `--expand`, `--restore`, and `-A` for array handling.
2. Based on the `--expand` or `--restore` flags, the function selects the appropriate transformation function (`expand_fn` or `restore_fn`) from `jsoncsv.jsontool`.
3. The function calls `convert_json` with the selected transformation, separator, safety mode, and array settings.
4. Input and output streams are properly closed after conversion.

The heavy lifting is delegated to utilities in [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py), specifically `convert_json`, `expand`, and `restore`, while [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py) focuses purely on CLI argument handling and orchestration.

## Using the jsoncsv CLI

### Basic Command-Line Usage

After installation, you can invoke the tool directly using the `jsoncsv` command:

```bash

# Expand JSON to CSV (default mode)

jsoncsv input.json output.csv

# Use custom separator (default is dot)

jsoncsv -s "_" data.json data.csv

# Restore previously expanded JSON

jsoncsv --restore expanded.json restored.json

# Enable safe mode (fails on non-JSON values)

jsoncsv --safe input.json output.csv

# Process JSON arrays

jsoncsv -A array.json array.csv

```

### Programmatic Invocation

You can also invoke the same entry point from Python code using Click's testing utilities or by importing the function directly:

```python
from jsoncsv.main import jsoncsv
from click.testing import CliRunner

runner = CliRunner()
result = runner.invoke(jsoncsv, ['examples/sample.json', '-'])
print(result.output)   # CSV output written to stdout

```

This approach is useful for testing, automation scripts, or integrating jsoncsv functionality into larger applications without shelling out to the command line.

## Summary

- The **CLI entry point for jsoncsv** is the `jsoncsv` function in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py), registered via [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml).
- The entry point is declared in the `[project.scripts]` section as `jsoncsv = "jsoncsv.main:jsoncsv"`.
- **Click** powers the argument parsing and help generation.
- The function delegates processing to `jsoncsv.jsontool.convert_json` and related utilities.
- You can invoke the CLI programmatically using `CliRunner` or import the function directly for testing.

## Frequently Asked Questions

### What file contains the jsoncsv CLI entry point?

The CLI entry point is defined in [`jsoncsv/main.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/main.py). This file contains the `jsoncsv` function that serves as the main command handler and is registered as the console script entry point in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml).

### How is the jsoncsv command registered for installation?

The command is registered in [`pyproject.toml`](https://github.com/alingse/jsoncsv/blob/main/pyproject.toml) under the `[project.scripts]` section with the line `jsoncsv = "jsoncsv.main:jsoncsv"`. This creates the `jsoncsv` executable when you install the package via pip.

### Can I call the jsoncsv CLI entry point from Python code?

Yes. You can import the `jsoncsv` function directly from `jsoncsv.main` and invoke it using Click's `CliRunner` for testing, or call it with appropriate arguments. This allows programmatic access without spawning a subprocess.

### What library powers the jsoncsv command-line interface?

The CLI uses the **Click** library to define commands, options, and help text. Click handles the parsing of flags like `--expand`, `--restore`, and `--safe`, then passes the processed arguments to the conversion logic in [`jsoncsv/jsontool.py`](https://github.com/alingse/jsoncsv/blob/main/jsoncsv/jsontool.py).