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:

# 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

jyml <file> [options]

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

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

Options

Common Workflows

Convert a single file

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

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

Convert with custom output path

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

Convert with custom indentation

jyml response.json --indent 4

Extract data programmatically

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

# 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:

# 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:

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

Structured mode (--json)

Prints structured JSON to stdout, no file written:

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

Exit Codes

Error Handling

Errors are printed to stderr with actionable context:

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:

# 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:

# ESLint config to YAML
jyml .eslintrc.json

# Docker Compose to JSON
jyml docker-compose.yml

GitHub Actions workflows

Parse workflow files for scripting:

# 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:

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