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.