jsonatacli

Run JSONata transforms over JSON, CSV, XML, and YAML from the command line.

It runs transform and pipeline files exported from JSONata Studio — design a transformation visually in the Studio, click Export CLI, and run the downloaded .json against your data anywhere.

Install

npm install -g @chiefdfo/jsonatacli     # global command
# or run without installing:
npx @chiefdfo/jsonatacli run transform.json --input data.json

Requires Node.js >= 22.

Usage

jsonatacli run  <transform.json> [options]   # run an exported Studio transform/pipeline file
jsonatacli eval <expression>     [options]   # run a raw JSONata expression (jq-style)

Options

  -i, --input <file|glob>     input file(s); omit to read stdin
  -o, --output <file>         output file; omit to write stdout
      --out-dir <dir>         batch mode: one mirrored output file per input
      --input-format  <fmt>   json|csv|xml|yaml (overrides extension)
      --output-format <fmt>   json|csv|xml|yaml (overrides extension; default json)
      --functions <file>      external custom-function definitions, merged over embedded
      --step <n>              pipeline only: emit step n's intermediate output (1-based)
      --timeout <ms>          best-effort eval guard (async expressions only)
  -h, --help                  show help
  -v, --version               show version

Input and output formats are inferred from file extensions and can be overridden with --input-format / --output-format. With no --input, the CLI reads stdin; with no --output, it writes stdout.

Examples

# Run an exported transform, JSON in, JSON out
jsonatacli run mytransform.json --input data.json

# CSV in, YAML out
jsonatacli run mytransform.json -i people.csv --output-format yaml

# Inline expression, piped input
echo '{"items":[1,2,3,4,5]}' | jsonatacli eval 'items[$ > 2]'

# Batch: transform every CSV into a mirrored JSON file
jsonatacli run mytransform.json -i "data/*.csv" --out-dir out/

# Inspect an intermediate pipeline step
jsonatacli run pipeline.json -i data.json --step 1

Exit codes

| Code | Meaning | |------|---------| | 0 | success | | 1 | evaluation error (results go to stdout, diagnostics to stderr) | | 2 | usage / IO / parse error |

Programmatic use

The package is also an importable library — the same engine the CLI runs, minus file and stream I/O. It ships as ESM with TypeScript types.

npm install @chiefdfo/jsonatacli

import { runTransform, transform, step, pipeline } from "@chiefdfo/jsonatacli";

// Single expression
const r = await runTransform(
  '{"items":[{"price":2},{"price":3}]}',
  transform("items.price ~> $sum()"),
);
r.ok && r.value; // 5

// Convert formats: CSV in, YAML out
await runTransform("name,age\nAda,36", transform("$"), {
  inputFormat: "csv",
  outputFormat: "yaml",
});

// A pipeline — step ids are generated, object bindings are serialized for you
const paidByRegion = pipeline(
  [
    // $region comes from the shared bindings; $minNet is a per-step override
    step("orders[status = 'paid' and region = $region and amount > $minNet]", {
      bindingOverrides: { minNet: 50 },
    }),
    step("$sum(amount)"),
  ],
  { bindings: { region: "EU" } }, // shared by every step
);
const out = await runTransform(inputJson, paidByRegion);

runTransform(input, transform, options?) resolves to a discriminated result:

{ ok: true; value: unknown; output: string } | { ok: false; error: string }

• value is the raw result; output is it serialized in outputFormat (default json).
• options: inputFormat, outputFormat (json | csv | xml | yaml), functions, step, timeout.

To run a transform or pipeline file exported from the Studio, parse its JSON and pass it straight to runTransform — it accepts the same shape (expression, pipelineSteps, bindings, embedded functions), so the builders above are optional conveniences.

Notes

• The bundle is self-contained (no runtime dependencies).
• Custom functions defined in the Studio are embedded in the exported file, so they work out of the box; --functions can add or override them.
• Input is decoded with BOM awareness (UTF-8 and UTF-16 LE/BE), so Windows PowerShell pipes (|) and redirects (>) work.

License

MIT