Output Formats

jpx supports multiple output formats beyond JSON, making it easy to integrate with other tools and workflows.

Available Formats

YAML Output

YAML is great for human-readable configuration files and nested data structures.

# Simple object
echo '{"name": "alice", "age": 30}' | jpx '@' --yaml

age: 30
name: alice

# Nested structures
echo '{"server": {"host": "localhost", "port": 8080}}' | jpx '@' -y

server:
  host: localhost
  port: 8080

# Arrays
echo '[{"name": "alice"}, {"name": "bob"}]' | jpx '@' --yaml

- name: alice
- name: bob

Use Cases

• Converting JSON configs to YAML for Kubernetes, Docker Compose, etc.
• Human-readable output for debugging
• Generating configuration files

# Extract and convert to YAML
jpx '[*].{name: name, role: role}' -f users.json --yaml > users.yaml

TOML Output

TOML is ideal for configuration files, especially in the Rust ecosystem.

# Simple object
echo '{"name": "myapp", "version": "1.0.0"}' | jpx '@' --toml

name = "myapp"
version = "1.0.0"

# Nested tables
echo '{"database": {"host": "localhost", "port": 5432}}' | jpx '@' --toml

[database]
host = "localhost"
port = 5432

Use Cases

• Generating Cargo.toml snippets
• Creating configuration files for Rust applications
• Converting JSON API responses to TOML configs

CSV Output

CSV format is perfect for tabular data that needs to go into spreadsheets or databases.

# Array of objects becomes a table
echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' --csv

age,name
30,alice
25,bob

Nested Object Flattening

Nested objects are automatically flattened using dot notation:

echo '[
  {"name": "alice", "address": {"city": "NYC", "zip": "10001"}},
  {"name": "bob", "address": {"city": "LA", "zip": "90001"}}
]' | jpx '@' --csv

address.city,address.zip,name
NYC,10001,alice
LA,90001,bob

Arrays in Cells

Arrays are JSON-encoded within cells:

echo '[{"name": "alice", "tags": ["admin", "dev"]}]' | jpx '@' --csv

name,tags
alice,"[""admin"",""dev""]"

Single Objects

A single object is output as a single-row table:

echo '{"name": "alice", "role": "admin"}' | jpx '@' --csv

name,role
alice,admin

Array of Primitives

Arrays of primitives become single-column output (no header):

echo '[1, 2, 3, 4, 5]' | jpx '@' --csv

1
2
3
4
5

Use Cases

• Exporting data for Excel or Google Sheets
• Loading into databases
• Generating reports

# Export user emails for a mailing list
jpx '[*].{email: email, name: name}' -f users.json --csv > contacts.csv

TSV Output

TSV (tab-separated values) works the same as CSV but uses tabs instead of commas. This is useful for:

• Unix command-line tools that expect tab-separated input
• Pasting directly into spreadsheets
• Avoiding issues with commas in data

echo '[{"name": "alice", "city": "New York"}, {"name": "bob", "city": "Los Angeles"}]' | jpx '@' --tsv

city	name
New York	alice
Los Angeles	bob

Use Cases

# Pipe to awk for further processing
jpx '[*].{name: name, score: score}' -f data.json --tsv | awk -F'\t' '$2 > 90'

# Pipe to column for pretty printing
jpx '@' -f users.json --tsv | column -t -s $'\t'

Lines Output (JSONL)

The --lines flag outputs one JSON value per line, also known as JSON Lines (JSONL) or newline-delimited JSON (NDJSON).

echo '[1, 2, 3, "hello", {"key": "value"}]' | jpx '@' --lines

1
2
3
"hello"
{"key":"value"}

# Array of objects
echo '[{"id": 1}, {"id": 2}, {"id": 3}]' | jpx '@' -l

{"id":1}
{"id":2}
{"id":3}

Use Cases

• Streaming processing with tools like jq, grep, or awk
• Log file format
• Parallel processing (each line is independent)
• Piping to other JSON tools

# Process each line with another tool
jpx '[*]' -f events.json --lines | while read -r line; do
  echo "$line" | jpx '.timestamp'
done

# Filter with grep
jpx '@' -f logs.json --lines | grep '"level":"error"'

# Count items
jpx '[*]' -f data.json --lines | wc -l

Table Output

The --table flag renders arrays of objects as formatted tables, perfect for terminal display.

echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' --table

┌───────┬─────┐
│ name  │ age │
├───────┼─────┤
│ alice │ 30  │
│ bob   │ 25  │
└───────┴─────┘

Table Styles

Use --table-style to choose different table formats:

# ASCII style (for older terminals)
echo '[{"name": "alice", "age": 30}]' | jpx '@' -t --table-style ascii

+-------+-----+
| name  | age |
+-------+-----+
| alice | 30  |
+-------+-----+

# Markdown style (for documentation)
echo '[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]' | jpx '@' -t --table-style markdown

| name  | age |
|-------|-----|
| alice | 30  |
| bob   | 25  |

Use Cases

• Quick data inspection in the terminal
• Generating markdown tables for documentation
• Human-readable output for reports

# Display users as a table
jpx '[*].{name: name, email: email, role: role}' -f users.json --table

# Generate markdown documentation
jpx '[*].{Function: name, Description: description}' -f functions.json -t --table-style markdown > docs/functions.md

Combining with Expressions

Output formats work with any JMESPath expression:

# Extract specific fields and output as YAML
echo '[{"name": "alice", "age": 30, "email": "alice@example.com"}]' | \
  jpx '[*].{name: name, email: email}' --yaml

- email: alice@example.com
  name: alice

# Filter and export as CSV
jpx '[?status == `active`].{id: id, name: name}' -f users.json --csv

# Aggregate and output as TOML
jpx '{total: length(@), active: length([?active])}' -f users.json --toml

active = 42
total = 100

Output to Files

All output formats work with the -o flag:

# Save as YAML
jpx '@' -f config.json --yaml -o config.yaml

# Save as CSV
jpx '[*].{name: name, email: email}' -f users.json --csv -o contacts.csv

# Save as TOML
jpx '@' -f settings.json --toml -o settings.toml

Format Selection Tips