JSON Toolbox CLI

Deterministic data transformation pipelines for JSON, CSV, XML, and YAML.

Features

• 🔧 42 Operators across 9 namespaces (json, csv, xml, yaml, transform, query, schema, diff, fix)
• 📊 Pipeline System - Chain operators with manifest files
• 🎯 Deterministic - Same input always produces same output
• 📦 Zero Dependencies - Pure JavaScript, no external libraries
• 🔒 Zero Telemetry - No data collection, offline-capable
• 🌐 Browser/CLI Parity - Same behavior everywhere

Installation

npm (Recommended)

npm install -g @mackan/json-toolbox

One-liner Installers

macOS/Linux:

curl -fsSL https://mackan.eu/tools/json/cli/install.sh | bash

Windows (PowerShell):

irm https://mackan.eu/tools/json/cli/install.ps1 | iex

Verify Installation

json-toolbox version
# json-toolbox v2.2.0

Quick Start

Execute Single Operators

# Format JSON
echo '{"a":1,"b":2}' | json-toolbox exec json.format

# Parse CSV to JSON
cat data.csv | json-toolbox exec csv.parse --header true

# Filter array
echo '[{"age":20},{"age":30}]' | json-toolbox exec transform.filter --key age --operator gt --value 25

# Convert XML to JSON
cat data.xml | json-toolbox exec xml.parse

Run Pipelines

Create a pipeline manifest csv-to-json.json:

{
  "name": "csv-to-json",
  "version": "1.0.0",
  "steps": [
    { "operator": "csv.parse", "params": { "header": true } },
    { "operator": "transform.sort", "params": { "key": "name" } },
    { "operator": "json.stringify", "params": { "indent": 2 } }
  ]
}

Execute:

json-toolbox run csv-to-json.json < input.csv > output.json

Commands

| Command | Description | |---------|-------------| | run <manifest> | Run a pipeline manifest | | exec <operator> | Execute a single operator | | validate <manifest> | Validate a pipeline manifest | | describe <operator> | Show detailed operator info | | list-operators | List all available operators | | help | Show help message | | version | Show version |

Operator Reference

Core Namespaces

| Namespace | Operators | Description | |-----------|-----------|-------------| | json | 10 | Parse, stringify, format, validate, path, keys, values, entries | | csv | 3 | Parse, stringify, transpose | | xml | 2 | Parse, stringify | | yaml | 2 | Parse, stringify |

Transform Namespace

| Namespace | Operators | Description | |-----------|-----------|-------------| | transform | 10 | Sort, filter, map, flatten, unique, reverse, slice, group, count, merge |

Query & Schema

| Namespace | Operators | Description | |-----------|-----------|-------------| | query | 2 | JSONPath, select | | schema | 2 | Generate, validate |

Utilities

| Namespace | Operators | Description | |-----------|-----------|-------------| | diff | 2 | Compare, patch | | fix | 2 | Repair, escape |

Get Operator Details

json-toolbox describe transform.filter

Operator: transform.filter
Description: Filter array by expression or key/value match
Input Type: array
Output Type: array

Parameters:
  --key [default: null]
      Object key to filter by
  --operator [default: eq]
      Filter operator: eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, exists, empty
  --value [default: null]
      Value to compare against
  --expression [default: null]
      Filter expression (e.g., "age > 18")

Examples:
  json-toolbox exec transform.filter --key age --operator gt --value 18 < users.json

Options

Global Options

| Option | Description | |--------|-------------| | --strict | Error on unknown parameters (default: warn) | | -v, --verbose | Show execution metrics and warnings |

Run Command Options

| Option | Description | |--------|-------------| | -i, --input <file> | Input file (default: stdin) | | -o, --output <file> | Output file (default: stdout) | | --dry-run | Show execution plan without running | | --minify | Minify output |

Examples

Data Conversion

# CSV → JSON
cat data.csv | json-toolbox exec csv.parse --header true | json-toolbox exec json.format

# JSON → YAML
cat data.json | json-toolbox exec yaml.stringify

# XML → JSON
cat data.xml | json-toolbox exec xml.parse | json-toolbox exec json.format

Data Transformation

# Sort and filter
echo '[{"n":"c"},{"n":"a"},{"n":"b"}]' | \
  json-toolbox exec transform.sort --key n | \
  json-toolbox exec transform.filter --key n --operator ne --value b

# Extract and dedupe
cat users.json | \
  json-toolbox exec transform.map --extract email | \
  json-toolbox exec transform.unique

# Group and count
cat orders.json | \
  json-toolbox exec transform.group --key status

Schema Generation

# Generate JSON Schema from sample
cat sample.json | json-toolbox exec schema.generate

# Validate against schema
echo '{"data":"test","schema":{...}}' | json-toolbox exec schema.validate

JSON Repair

# Fix malformed JSON
echo "{'key': 'value',}" | json-toolbox exec fix.repair

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Invalid manifest | | 3 | Invalid input | | 10 | Unknown operator | | 11 | Unknown parameter (strict mode) |

Presets

The CLI includes example pipeline presets in the presets/ directory:

• csv-to-json.json - Parse CSV and format as JSON
• json-to-yaml.json - Convert JSON to YAML
• data-cleanup.json - Remove duplicates and sort
• generate-schema.json - Generate JSON Schema
• xml-to-json.json - Parse XML to JSON

Comparison with Other Tools

| Feature | json-toolbox | jq | yq | miller | |---------|-------------|-----|-----|--------| | JSON support | ✅ | ✅ | ✅ | ✅ | | CSV support | ✅ | ❌ | ❌ | ✅ | | XML support | ✅ | ❌ | ✅ | ❌ | | YAML support | ✅ | ❌ | ✅ | ❌ | | Pipeline manifests | ✅ | ❌ | ❌ | ❌ | | Schema generation | ✅ | ❌ | ❌ | ❌ | | JSON repair | ✅ | ❌ | ❌ | ❌ | | Browser parity | ✅ | ❌ | ❌ | ❌ | | Zero dependencies | ✅ | ❌ | ❌ | ❌ |

Development

# Run tests
npm test

# Run parity tests
npm run test:parity

# Run all tests
npm run test:all

Links

• Web App: https://mackan.eu/tools/json/
• Documentation: https://mackan.eu/tools/json/docs/
• GitHub: https://github.com/mackan-eu/json-toolbox
• npm: https://www.npmjs.com/package/@mackan/json-toolbox

License

MIT License - see LICENSE for details.

Made with ❤️ by mackan.eu