Deterministic data transformation pipelines - CLI for JSON, CSV, XML, YAML
npm install @mackan_eu/json-toolboxbash
npm install -g @mackan/json-toolbox
`
$3
macOS/Linux:
`bash
curl -fsSL https://mackan.eu/tools/json/cli/install.sh | bash
`
Windows (PowerShell):
`powershell
irm https://mackan.eu/tools/json/cli/install.ps1 | iex
`
$3
`bash
json-toolbox version
json-toolbox v2.2.0
`
Quick Start
$3
`bash
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
`
$3
Create a pipeline manifest csv-to-json.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:
`bash
json-toolbox run csv-to-json.json < input.csv > output.json
`
Commands
| Command | Description |
|---------|-------------|
| run | Run a pipeline manifest |
| exec | Execute a single operator |
| validate | Validate a pipeline manifest |
| describe | Show detailed operator info |
| list-operators | List all available operators |
| help | Show help message |
| version | Show version |
Operator Reference
$3
| 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 |
$3
| Namespace | Operators | Description |
|-----------|-----------|-------------|
| transform | 10 | Sort, filter, map, flatten, unique, reverse, slice, group, count, merge |
$3
| Namespace | Operators | Description |
|-----------|-----------|-------------|
| query | 2 | JSONPath, select |
| schema | 2 | Generate, validate |
$3
| Namespace | Operators | Description |
|-----------|-----------|-------------|
| diff | 2 | Compare, patch |
| fix | 2 | Repair, escape |
$3
`bash
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
$3
| Option | Description |
|--------|-------------|
| --strict | Error on unknown parameters (default: warn) |
| -v, --verbose | Show execution metrics and warnings |
$3
| Option | Description |
|--------|-------------|
| -i, --input | Input file (default: stdin) |
| -o, --output | Output file (default: stdout) |
| --dry-run | Show execution plan without running |
| --minify | Minify output |
Examples
$3
`bash
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
`
$3
`bash
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
`
$3
`bash
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
`
$3
`bash
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
`bash
Run tests
npm test
Run parity tests
npm run test:parity
Run all tests
npm run test:all
``