jq-lite

jq-lite is a lightweight, jq-compatible alternative JSON processor written in pure Perl.

It is designed for long-term CLI stability and minimal dependencies, making it suitable as an OS-level JSON utility in constrained or long-lived environments.

• No external binaries
• No native libraries
• No compilation step
• Stable, test-backed CLI contract

Overview

jq-lite allows querying and transforming JSON using jq-like syntax, while remaining fully portable across systems where Perl is available.

It is particularly suited for:

• minimal Linux distributions
• containers and CI environments
• legacy or restricted systems
• offline / air-gapped deployments
• environments where jq cannot be installed

jq-lite is available as an official Alpine Linux package:

apk add jq-lite

Design Goals

• Stable CLI contract Exit codes, stderr prefixes, and error behavior are treated as long-term compatibility promises.

• Minimal dependency footprint Implemented in pure Perl without XS, C extensions, or external libraries.

• Predictable behavior Intended for use in shell scripts, CI pipelines, and infrastructure automation.

jq-lite intentionally prioritizes reliability over feature growth.

Stable CLI Contract

jq-lite defines a fully implemented, test-backed CLI contract that serves as a strict backward-compatibility guarantee.

The contract specifies:

• Exit codes and their meanings
• Error categories and stderr prefixes
• stdout behavior on success and failure
• jq-compatible truthiness semantics (-e/--exit-status)
• Broken pipe (SIGPIPE/EPIPE) behavior suitable for pipelines and CI

📄 Contract specification: 👉 docs/cli-contract.md

Any change that would violate this contract requires a major version bump and is intentionally avoided.

Environment Support

| Environment | jq | jq-lite | | -------------------- | -- | ------- | | Alpine Linux | △ | ✓ | | Legacy hosts | ✗ | ✓ | | Air-gapped systems | ✗ | ✓ | | No root privileges | △ | ✓ |

Runs on Perl ≥ 5.14.

Installation

Package Manager

Alpine Linux

apk add jq-lite

CPAN

cpanm JQ::Lite

From Source (Latest, Simple)

This method installs the latest released version directly from CPAN without requiring jq.

Download (latest)

curl -sSfL https://cpan.metacpan.org/authors/id/I/IS/ISHIGAKI/JSON-PP-4.16.tar.gz -o JSON-PP.tar.gz
tar xzf JSON-PP.tar.gz

JSONPP_LIB=$(echo JSON-PP-*/lib)

ver=$(curl -s http://fastapi.metacpan.org/v1/release/JQ-Lite \
  | perl -I"$JSONPP_LIB" -MJSON::PP -0777 -ne 'print decode_json($_)->{version}')
curl -sSfL http://cpan.metacpan.org/authors/id/S/SH/SHINGO/JQ-Lite-$ver.tar.gz -o JQ-Lite-$ver.tar.gz

Install (user-local, no root, offline-friendly)

jq-lite can be installed without network access or system package managers.

Typical use cases:

• air-gapped environments
• restricted corporate networks
• systems without root privileges
• legacy hosts

tar xzf JQ-Lite-$ver.tar.gz
export PATH="$PWD/JQ-Lite-$ver/bin:$PATH"

Verify:

jq-lite -v

Install (system-wide / root)

tar xzf JQ-Lite-$ver.tar.gz
cd JQ-Lite-$ver

perl Makefile.PL
make
make test
sudo make install

Windows (PowerShell)

.\install-jq-lite.ps1 JQ-Lite-<version>.tar.gz

Administrator privileges are not required.

Containers

FROM alpine
RUN apk add --no-cache jq-lite

jq-lite can be used as a container-standard JSON processing tool without introducing native dependencies.

Perl Integration

jq-lite can also be used directly from Perl code:

use JQ::Lite;

my $jq = JQ::Lite->new;
say for $jq->run_query($json, '.users[].name');

Documentation

• docs/cli-contract.md — stable, test-backed CLI contract
• docs/FUNCTIONS.md — supported jq functions
• docs/DESIGN.md — design principles and scope
• CPAN documentation

License

Same terms as Perl itself.