btk convertCopy Anchor Link

Convert between JSON, YAML, TOML, XML, JSON5, JSONC and JSONL with the parsers built into Bun. You don't need jq, yq or a Python script.

CommandsCopy Anchor Link

runCopy Anchor Link

btk convert [files...] converts to JSON unless you pass --to. One input prints the result on stdout. Several inputs, a folder or --out-dir write files instead.

btk convert config.yaml                              # JSON on stdout
btk convert data.xml --to yaml                       # YAML on stdout
btk convert tsconfig.json --to yaml -o tsconfig.yaml # into a file
btk convert config.yaml --to toml --write            # config.toml next to config.yaml
cat logs.jsonl | btk convert --from jsonl            # standard input needs --from unless it is JSON, JSONL or XML
btk convert ./config -r --to toml --out-dir build    # a folder, mirrored into build/
btk convert ./config -r --to json --dry-run          # show what would be written
btk convert notes.txt --from yaml                    # a file with an unknown extension

formatsCopy Anchor Link

btk convert formats prints the table in Formats, so you can check what a build of btk supports.

btk convert formats
btk convert formats --json

When to use itCopy Anchor Link

Read a YAML or TOML file with a JSON tool. Convert it on the fly and pipe it into jq, or into any script that expects JSON:

btk convert docker-compose.yml | jq '.services | keys'
btk convert Cargo.toml | jq -r '.package.version'

Move a config to the format a tool now wants. Many tools accept both YAML and JSON. Convert once and save the result:

btk convert .eslintrc.yaml -o .eslintrc.json

Use an XML feed from a script. Turn the feed into JSON, then pick out what you need:

curl -fsSL https://github.com/oven-sh/bun/releases.atom | btk convert --to json | jq -r '.feed.title'

Turn log lines into one document. Structured logs are often JSONL, one JSON object per line. Convert them into a single JSON array for a spreadsheet, a chart or another tool:

cat app.jsonl | btk convert --from jsonl > app.json

Check that a config file is valid. Converting fails with the format's error message and exit code 1 when the file doesn't parse, which makes it a quick check in CI or a git hook:

btk convert config.toml > /dev/null

Convert a whole folder. Move fixtures, translations or configs from one format to another in one run, written next to the originals or into another folder:

btk convert ./fixtures -r --to json --out-dir ./fixtures-json

Look before you save. btk convert --ui lets you pick a file and a target format, shows the converted text, and writes it when you press w.

Where the result goesCopy Anchor Link

When btk writes files it follows the same rules as btk image:

• It never replaces an existing file without --overwrite.
• It never rewrites a file in place, such as app.json converted to JSON, without --overwrite.
• It leaves earlier outputs alone, so on a second run app.json next to app.yaml isn't treated as a new source.
• When two inputs would write the same file, such as app.json and app.yaml both becoming app.toml, the first in sort order wins and btk skips the other with a reason.
• It writes through a temp file, and --dry-run shows what would be written.

FormatsCopy Anchor Link

btk takes the input format from the file extension. For standard input, it recognizes JSON, JSONL and XML by trying to parse them. Anything else needs --from, because almost any text is valid YAML. --from also lets you name a file with another extension, such as btk convert notes.txt --from yaml. Folder scans still only pick up the extensions above.

Bun has no JSONC writer, and JSONC output would be plain JSON anyway, so write JSON instead.

How values map between formatsCopy Anchor Link

• TOML dates stay dates when converting TOML to TOML. Every other format gets the ISO 8601 string, such as 1979-05-27T07:32:00Z.
• TOML needs an object at the top level. Converting a list to TOML fails with a hint to convert to JSON or YAML instead.
• XML needs exactly one root element. An object with one key becomes that element. btk wraps anything else in <root> (--xml-root renames it), and a list becomes <root><item>…</item></root>.
• XML attributes appear as @name keys and text next to attributes as #text, which is Bun's compact XML shape.
• JSONL writes one JSON value per line. A list becomes one line per item, and anything else becomes a single line.
• JSONL input is strict. A bad line fails with its line number instead of stopping quietly at the last good value.
• A multi-document YAML file becomes a list of documents.

OptionsCopy Anchor Link

Every config key can also be set with BTK_CONVERT_<KEY>, such as BTK_CONVERT_TO=yaml.

ErrorsCopy Anchor Link

A parse error names the format, such as Invalid YAML: Unexpected token, and suggests --from in case the format guess was wrong. When converting several files, a failure doesn't stop the batch. Every file gets a row, and the command exits 1 at the end.

JSON modeCopy Anchor Link

With --json, a single conversion returns { "mode": "stdout", "from", "to", "output" }, where output holds the converted text. A batch returns { "mode": "batch", "files", "totals" } with one entry per file.

Dashboard (btk convert --ui)Copy Anchor Link

1. Browse. Only data files are listed. Highlight one and press enter.
2. Format. Pick the target format, starting on your configured default.
3. Preview. The converted text with line numbers, scrollable with the arrow keys. w writes it next to the original, following the same overwrite rules as the CLI. A file that fails to parse shows the error instead.