Built with Crystal CI Latest release oq oq oq-bin

A performant, portable jq wrapper thats facilitates the consumption and output of formats other than JSON; using jq filters to transform the data.



A statically linked binary for Linux x86_64 as available on the Releases tab. Additionally it can also be installed via various package managers.


For more on installing & using snap with your Linux distribution, see the official documentation.

sudo snap install oq

Arch Linux

Using yay:

yay -S oq

A pre-compiled version is also available:

yay -S oq-bin


brew install oq

From Source

If building from source, jq will need to be installed separately. Installation instructions can be found in the official documentation.

Requires Crystal to be installed, see the installation documentation.

git clone https://github.com/Blacksmoke16/oq.git
cd oq/
shards build --production --release

The built binary will be available as ./bin/oq. This can be relocated elsewhere on your machine; be sure it is in your PATH to access it as oq.


oq can easily be included into a Docker image by fetching the static binary from Github for the version of oq that you want.

# Set an arg to store the oq version that should be installed.

# Grab the binary from the latest Github release and make it executable; placing it within /usr/local/bin.  Can also put it elsewhere if you so desire.
RUN wget https://github.com/Blacksmoke16/oq/releases/download/v${OQ_VERSION}/oq-v${OQ_VERSION}-linux-x86_64 -O /usr/local/bin/oq && chmod +x /usr/local/bin/oq

# Or using curl (needs to follow Github's redirect):
RUN curl -L -o /usr/local/bin/oq https://github.com/Blacksmoke16/oq/releases/download/v${OQ_VERSION}/oq-v${OQ_VERSION}-linux-x86_64 && chmod +x /usr/local/bin/oq

# Also be sure to install jq if it is not already!

Existing Crystal Project

Add the following to your shard.yml and run shards install.

    github: blacksmoke16/oq
    version: ~> 1.3.0



Use the oq binary, with a few optional custom arguments, see oq --help. All other arguments get passed to jq. See jq manual for details.


Checkout the API Documentation for using oq within an existing Crystal project.


Consume JSON and output XML

$ echo '{"name": "Jim"}' | oq -o xml .
<?xml version="1.0" encoding="UTF-8"?>

Consume YAML from a file and output XML


name: Jim
  - 1
  - 2
  - 3
$ oq -i yaml -o xml . data.yaml 
<?xml version="1.0" encoding="UTF-8"?>

Use oq as a library, consuming some raw JSON input, convert it to YAML, and write the transformed data to a file.

require "oq"

# This could be any `IO`, e.g. an `HTTP` request body, etc.
input_io = IO::Memory.new %({"name":"Jim"})

# Create a processor, specifying that we want the output format to be `YAML`.
processor = OQ::Processor.new output_format: :yaml

File.open("./out.yml", "w") do |file|
  # Process the data using our custom input and output IOs.
  # The first argument represents the input arguments;
  # i.e. the filter and/or any other arguments that should be passed to `jq`.
  processor.process ["."], input: input_io, output: file


  1. Fork it (https://github.com/Blacksmoke16/oq/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request