file-querier

A jq-compatible CLI tool for querying and transforming structured data across multiple formats. Installed as fq.

Supports JSON, CSV, YAML, TOML, and XML with automatic format detection.

Installation

npm install -g file-querier

Or build from source:

git clone https://github.com/WalshyDev/file-querier.git
cd file-querier
npm install
npm run build
npm link

Quick Start

# Query JSON
echo '{"name":"Alice","age":30}' | fq '.name'
# "Alice"

# Query a file directly
fq '.users[0]' data.json

# Convert between formats
cat data.csv | fq '.' -o yaml

# Filter records
fq '.[] | select(.age > 25)' users.json

Formats

fq auto-detects the input format from the file extension or content. You can also force it with -f:

| Format | Extensions | Flag | |--------|-----------|------| | JSON | .json | -f json | | CSV | .csv | -f csv | | YAML | .yaml, .yml | -f yaml | | TOML | .toml | -f toml | | XML | .xml | -f xml |

Output format defaults to JSON but can be changed with -o:

# CSV to YAML
printf 'name,age\nAlice,30\n' | fq '.' -f csv -o yaml

# JSON to TOML
echo '{"server":{"host":"localhost","port":8080}}' | fq '.' -o toml

Features

jq-Compatible Syntax

fq implements the core jq filter language:

• Field access: .name, .user.address.city
• Array indexing: .[0], .[-1], .[2:4]
• Iteration: .[], .users[]
• Pipes: .users | .[] | .name
• Comma: .a, .b
• Object construction: {name: .first, age}
• Array construction: [.[] | .name]
• Conditionals: if . > 0 then "pos" else "neg" end
• Try-catch: try .foo catch "default"
• Reduce: reduce .[] as $x (0; . + $x)
• Variable binding: .width as $w | .height as $h | ($w * $h)
• User-defined functions: def double: . * 2; map(double)
• Alternative operator: .x // "default"
• String interpolation: "hello \(.name)" and "hello $.name"

Built-in Functions

Core: length, keys, values, has, in, type, empty, error, null, true, false, not, map, select, recurse, env, path, getpath, setpath, delpaths, to_entries, from_entries, with_entries, add, any, all, flatten, range, limit, first, last, nth, input, debug, halt, builtins

Array: sort, sort_by, group_by, unique, unique_by, reverse, contains, inside, min, max, min_by, max_by, indices, index, rindex, transpose, until, while, repeat, foreach

String: test, match, capture, scan, split, join, ltrimstr, rtrimstr, startswith, endswith, ascii_downcase, ascii_upcase, tostring, tonumber, ascii, explode, implode, gsub, sub, trim, tojson, fromjson

Math: floor, ceil, round, sqrt, pow, log, fabs, nan, isinfinite, isnan, infinite

Format strings: @base64, @base64d, @uri, @html, @csv, @tsv, @sh, @json, @text

CLI Reference

Usage: fq <filter> [file]

Positionals:
  filter  jq filter expression                                        [required]
  file    Input file (reads stdin if omitted)

Options:
  -f, --format      Force input format (json, csv, yaml, toml, xml)
  -o, --output      Output format                              [default: "json"]
  -r, --raw-output  Output raw strings without quotes
  -c, --compact     Compact output (no indentation)
  -s, --slurp       Read all inputs into an array
  -n, --null-input  Use null as input
  -R, --raw-input   Read each line as a string
      --tab         Use tabs for indentation
      --indent      Number of spaces for indentation           [default: 2]
  -S, --sort-keys   Sort object keys
  -h, --help        Show help
  -v, --version     Show version

Examples

# Pretty-print a JSON file
fq '.' data.json

# Get all user names from a JSON array
fq '[.[] | .name]' users.json

# Convert CSV to JSON, filtering rows
printf 'name,age\nAlice,30\nBob,22\n' | fq '[.[] | select(.age > 25)]' -f csv

# Extract nested XML data
echo '<catalog><book><title>Hello</title></book></catalog>' | fq '.catalog.book.title' -f xml

# Group and aggregate
fq 'group_by(.category) | map({category: .[0].category, count: length})' items.json

# String interpolation with dollar shorthand
echo '{"name":"Alice"}' | fq '"Hello $.name!"' -r

# Sort, deduplicate, and format
fq 'sort | unique | join(", ")' -r names.json

For a comprehensive guide with more examples, see GUIDE.md.

License

MIT