tq

tq is a tiny Python package and CLI for querying JSON records from files or stdin.

It reads JSON Lines, arrays of JSON objects, multiline objects, and consecutive JSON objects, then writes matching records as JSON. You can pair it with jq to extract or prepare records.

Get started

Install:

pip install tq-json         # package only
pip install "tq-json[cli]"  # with CLI support

Try tq with OpenRouter models from models.dev:

# Extract models with jq
curl -fsSL https://models.dev/catalog.json \
  | jq '.providers.openrouter.models[] | {id, modalities, limit, reasoning, tool_call}' -c \
  > models.jsonl

# Query with tq
tq 'openai/*[reasoning;tool_call]' models.jsonl
tq '[limit.context>=200000]' models.jsonl
tq '[modalities.input has image]' models.jsonl
tq '[modalities.input has all (text,image)]' models.jsonl

CLI

usage: tq [OPTIONS] QUERY [FILE]

Arguments:
  query                 match expression
  file                  JSON input file; defaults to stdin

Options:
  -h, --help            show this help message and exit
  -k KEY                identity field (default: ref, then id)
  -r, --reorder         order matches by query branch, then input position
  -C, --color           force colored output
  -M, --no-color        force uncolored output
  -c, --compact         compact JSON output, one record per line

Color is automatic for terminals (unless NO_COLOR is set) and plain for pipes; -C and -M override it. -c only controls JSON formatting.

Query syntax

A query is a comma-separated list of branches. Each branch may combine an identity pattern with predicates:

IDENTITY[PREDICATE;PREDICATE],IDENTITY[PREDICATE]

Omit the identity to match any record. Branches are OR-ed; predicates within a branch are AND-ed and may be separated by commas or semicolons.

has any, has all, and has none require at least two candidates.

Quote values when needed; for example, "true" is the text value true. Missing fields never match a predicate, including negative predicates. Explicit null is distinct from a missing field.

Python API

from tq import Query

schema = {"key": "id", "filter": ["reasoning", "tool_call"]}
query = Query.parse("openai/*[reasoning;tool_call]").validate(schema)

record = {
    "id": "openai/gpt-5",
    "reasoning": True,
    "tool_call": True,
}

branch = query.match(record)

Publishing

See PUBLISHING.md for PyPI Trusted Publishing setup and release instructions.