konvert

A tiny, fast command-line tool that converts structured data between JSON, YAML, CSV, TOML, XML and Java .properties — written in Kotlin.

konvert reads any supported format into a single in-memory model and writes it back out in whatever format you ask for. Formats are auto-detected from file extensions, with --from / --to overrides so it also works in shell pipelines.

konvert data.json -o data.yaml      # JSON -> YAML
cat data.json | konvert -f json -t csv   # JSON (stdin) -> CSV (stdout)

Why it exists

Moving a config or dataset from one format to another usually means hunting for a one-off website or writing a throwaway script. konvert is a single, small binary that does it offline, scriptably, and consistently — the same tool whether you're flipping a YAML config to TOML or turning an API's JSON response into a CSV you can open in a spreadsheet.

Features

• 🔄 Convert between 6 formats: JSON, YAML, CSV, TOML, XML, .properties
• 🪄 Auto-detects formats from file extensions
• 🧱 Built on the battle-tested Jackson data-format modules
• 📥 Reads from a file or stdin, writes to a file or stdout — pipe-friendly
• 🎛️ Pretty (default) or --compact output
• 🧩 Clear, friendly error messages (no raw stack traces)
• ✅ Covered by unit tests and CI

How it works

Instead of writing a converter for every pair of formats (which would be N×N), konvert routes everything through one neutral model:

flowchart LR
    A[Input bytes] -->|parse| M([Generic model<br/>maps / lists / scalars])
    M -->|render| B[Output bytes]
    subgraph in ["any source format"]
      A
    end
    subgraph out ["any target format"]
      B
    end

Loading

So adding a new format only means teaching the read and write steps about it — and it instantly converts to/from every other format. CSV is the one special case: being tabular, it maps to a list of rows rather than an arbitrary tree.

Requirements

• JDK 17+
• Gradle (or the Gradle wrapper once generated)

Build

# Generate the Gradle wrapper once (if you don't have it yet)
gradle wrapper

# Build a runnable distribution
./gradlew installDist

The runnable script lands at build/install/konvert/bin/konvert.

During development you can run straight from Gradle:

./gradlew run --args="examples/people.json --to csv"

Usage

Usage: konvert [OPTIONS] [INPUT]

  Convert structured data between JSON, YAML, CSV, TOML, XML and .properties.

Arguments:
  INPUT  Input file. Omit or use '-' to read from stdin.

Options:
  -o, --output PATH   Output file. Defaults to stdout.
  -f, --from FORMAT   Source format (json|yaml|csv|toml|xml|properties).
  -t, --to FORMAT     Target format (json|yaml|csv|toml|xml|properties).
  -c, --compact       Compact output (disable indentation).
  -V, --version       Print the konvert version and exit.
      --list-formats  List the supported formats and exit.
  -h, --help          Show this message and exit.

Examples

# JSON file -> YAML file (formats detected from extensions)
konvert examples/people.json -o people.yaml

# YAML -> TOML, printed to stdout
konvert examples/config.yaml --to toml

# Pipe JSON through stdin and get CSV on stdout
cat examples/people.json | konvert --from json --to csv

# .properties -> JSON
konvert examples/server.properties --to json

# Object -> XML
konvert examples/config.yaml --to xml

# Compact JSON output
konvert examples/config.yaml --to json --compact

# See what's supported
konvert --list-formats

Notes on CSV

CSV is tabular, so converting to CSV expects either an array of objects or a single object; the header is the union of keys across all rows. Converting from CSV produces an array of objects keyed by the header row.

Notes on XML

XML needs a single root element, so output is wrapped in <root>...</root>. A top-level array is wrapped as <root><item>...</item></root>.

Project layout

konvert/
├── build.gradle.kts
├── settings.gradle.kts
├── .github/workflows/ci.yml   # build + test on every push / PR
├── examples/                  # sample inputs to play with
└── src/
    ├── main/kotlin/com/konvert/
    │   ├── Main.kt                # CLI entry point (clikt)
    │   ├── Format.kt              # Supported formats + extension detection
    │   ├── Converter.kt           # Read/write engine
    │   └── ConversionException.kt # One clean error type
    └── test/kotlin/com/konvert/
        ├── ConverterTest.kt
        └── FormatTest.kt

Test

./gradlew test

Roadmap

• INI and .env formats
• JSON Lines (.jsonl) support
• Streaming mode for very large files
• Native binary via GraalVM for instant startup

Contributing

Contributions are welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.