gq is a jq-like command-line tool written in Go, inspired by one of John Crickett’s coding challenges. It aims to provide a fast, simple, and expressive way to query and transform JSON data from the command line.

This project is a work in progress and is intentionally being developed as a learning and exploration exercise.

In particular, gq has served as a personal case study to practice:

• CLI design and common command-line patterns
• Building parsers
• Performance analysis and optimization in Go

An article detailing these learnings and trade-offs is planned.

gq is available via Homebrew using the jmpargana/tools tap:

brew tap jmpargana/tools
brew install gq

A Docker image is published at:

jmpargana/gq

You can pull it with:

docker pull jmpargana/gq

gq is designed to work in a similar way to jq, reading JSON from standard input and applying a query expression.

cat input.json | gq '.[0]'

When using Docker, make sure to keep stdin open:

cat input.json | docker run -i jmpargana/gq '.[0]'

Given an input file input.json:

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "age": 25 }
]

You can run:

cat input.json | gq '[{newName: .[] | .name}]' # or '[.[] | {newName: .name}]'

Output:

[
  {
    "newName": "Alice"
  },
  {
    "newName": "Bob"
  }
]

Local development follows standard Go CLI conventions.

Requirements:

• Go (recent version recommended)
• Make

Common tasks are available via the Makefile:

make build
make test

This will build the gq binary and run the test suite.

A Dockerfile is included and can be used to build and run the tool locally:

docker build -t gq .
cat input.json | docker run -i gq '.[0]'

The Docker image is built using a minimal base and is ready to run without additional dependencies.

Releases are automated using GoReleaser and include:

• Homebrew formula updates
• Multi-platform binaries
• Docker images