jyml - YAML ↔ JSON Converter#

Zero-config CLI for converting between YAML and JSON formats. Pass a file, get the converted file. No flags required.

Prerequisites#

Ensure jyml is available:

bash

# Check if installed
which jyml

# Install globally if needed
npm install -g jyml

# Or use npx for one-off conversions
npx jyml <file>

Requires Node.js 18 or later.

Basic Usage#

bash

jyml <file> [options]

The CLI auto-detects the input format based on file extension and converts to the opposite format:

Input ExtensionOutput Extension.yaml, .yml``.json``.json``.yaml

Output is written to the same directory with the swapped extension.

Options#

OptionDescriptionDefault-o, --output <path>Custom output file pathInput file with swapped extension--jsonPrint structured JSON to stdout (no file written)—--indent <n>Indentation spaces2``-h, --helpShow help—-V, --versionShow version—

Common Workflows#

Convert a single file#

bash

# YAML to JSON
jyml config.yaml
# → writes config.json

# JSON to YAML
jyml settings.json
# → writes settings.yaml

Convert with custom output path#

bash

jyml docker-compose.yml -o ./output/docker-compose.json

Convert with custom indentation#

bash

jyml response.json --indent 4

Extract data programmatically#

Use --json to get structured output for piping to other tools:

bash

# Get parsed content
jyml workflow.yml --json | jq '.content'

# Extract specific values
jyml .github/workflows/ci.yml --json | jq '.content.jobs'

Batch conversion#

Convert multiple files using shell patterns:

bash

# Convert all YAML files in a directory
for f in configs/*.yaml; do jyml "$f"; done

# Convert all JSON files
for f in data/*.json; do jyml "$f"; done

Output Modes#

Default mode (file output)#

Writes converted content to a file, prints progress to stderr:

bash

jyml config.yaml
# stderr: Converting config.yaml → config.json
# Creates: config.json

Structured mode ( --json)#

Prints structured JSON to stdout, no file written:

json

{
  "input": "/path/to/input.yaml",
  "format": "json",
  "output": "/path/to/input.json",
  "content": { ... }
}

FieldTypeDescriptioninput``stringAbsolute path to the source fileformat``stringOutput format: "json" or "yaml"``output``stringPath where the file would be writtencontent``objectThe parsed and converted data

Exit Codes#

CodeMeaning0Success1Conversion error (invalid YAML/JSON, I/O failure)2Invalid usage (missing file, bad arguments, unsupported extension)

Error Handling#

Errors are printed to stderr with actionable context:

text

Error: File not found: config.yaml
Error: Unsupported file extension ".txt". Supported: .yaml, .yml, .json
Error: Invalid YAML: bad indentation of a mapping entry (1:11)
Error: Invalid JSON: Expected property name or '}' in JSON at position 2

When conversion fails, check:

1. File exists and is readable
2. File extension is .yaml, .yml, or .json
3. File contains valid YAML or JSON syntax

Use Cases#

OpenAPI/Swagger specs#

Convert specs between formats for different tools:

bash

# Convert OpenAPI spec to JSON for code generators
jyml openapi.yaml

# Convert back to YAML for documentation
jyml openapi.json

Configuration files#

Switch config formats based on tool requirements:

bash

# ESLint config to YAML
jyml .eslintrc.json

# Docker Compose to JSON
jyml docker-compose.yml

GitHub Actions workflows#

Parse workflow files for scripting:

bash

# Extract job names from a workflow
jyml .github/workflows/ci.yml --json | jq '.content.jobs | keys'

API response inspection#

Convert JSON responses to readable YAML:

bash

curl -s https://api.example.com/data > response.json
jyml response.json --indent 4
cat response.yaml