CLI · JSON processing · jq contributors
jq
Filter and reshape JSON in the terminal so API output becomes a small, readable answer or a predictable input for the next step.
Filter construction can change the program. Concatenating untrusted values into a filter or shell command creates avoidable ambiguity. Use argument binding and a fixed reviewed filter.
Understand the tool
What it does.
jq is a standalone command-line processor for JSON. Its filter language selects fields, transforms arrays and builds new objects. It is useful wherever another tool returns structured data and you want a repeatable transformation you can read and review.
Why use it?
Reach for jq when an API response is too large to inspect manually or a script needs a stable set of fields. Keep input values separate from filter code, then check the exit status and output shape before another command uses the result.
A useful fit for
- Extracting a few fields from API responses
- Checking JSON in scripts
- Preparing small, explicit data exports
From need to output
Ways to put it to work.
These are suggested workflows based on the documented capabilities. They are not recorded runtime results.
Use case 01
Turn a response into a work queue
An export contains many records but a reviewer needs only queued items and their owners.
- Save a permitted JSON response to a local file.
- Filter by status and construct objects containing only the required fields.
- Check record counts and missing fields before sharing the result.
Intended outputA focused queue that is easier to review than the full response.
Use case 02
Validate an automation input
A script must reject malformed JSON before passing identifiers to another tool.
- Parse the input with jq and stop when parsing fails.
- Use an explicit filter to check the required shape or condition.
- Handle no-result and error exit statuses separately.
Intended outputA predictable handoff that fails visibly when the input is unusable.
A concrete starting point
Select queued requests
Assumes requests.json is an array with status, id and owner fields. --arg passes queued as data. This example uses a different fixture from the executed tests.
jq --arg state queued '[.[] | select(.status == $state) | {id, owner}]' requests.jsonWhat this can change
Reads the named file and prints selected fields; it does not edit the file. The fields you choose can still contain confidential values.
This example has not been executed for this review. Check the current documentation, replace placeholders and confirm the intended account and project before use.
Before you start
Setup and access.
What you’ll need
- A jq binary for the operating system
- JSON input and a filter matched to its structure
- Shell quoting appropriate to your terminal
- Authentication
- No account is needed for local JSON processing. Any upstream API authentication belongs to the tool that obtains the input.
- Can read
- Standard input and explicitly supplied JSON files
- Additional files passed through supported file arguments
- Can write or change
- Standard output; file writes only when the surrounding shell or workflow redirects it
- Network and data flow
- No service is needed for the local processing shown here
- Approval and control
- jq executes the filter supplied to it. Treat filter source and shell syntax as code; pass variable values with --arg or --argjson as appropriate.
Check your environment
Compatibility, costs and license.
Compatibility notes
- Windows, macOS and Linux
- Standalone official binaries; shell quoting differs across terminals
Costs and account requirements
No software subscription is required for the open-source CLI. Upstream data services can charge separately.
Current pricing or plan information ↗MIT with third-party notices
The core uses MIT terms; bundled components and documentation carry additional notices in COPYING.
Read the license or service terms ↗Keep the boundaries visible
Concerns and limitations.
Filter construction can change the program
Concatenating untrusted values into a filter or shell command creates avoidable ambiguity. Use argument binding and a fixed reviewed filter.
A short output can still expose data
Field selection is only as careful as the selected fields. Inspect exports before placing them in logs or shared artifacts.
Where it may fall short
- The filter must match the input schema; JSON parsing alone does not validate business meaning.
- Large inputs and transformations can consume substantial memory; this evaluation is not a performance benchmark.
Observed behavior · 2026-10-18
Runtime and security findings.
jq selected the expected two records, preserved filter-looking --arg text as data and returned distinct nonzero results for an empty selection and malformed JSON.
These checks cover the conditions below. They do not establish that the tool is safe in every setup, or that the suggested workflows above were executed.
What we found
Observed in this evaluation
Argument binding kept this value out of filter code
The string containing quotes and error("injected") was returned literally through --arg, with exit 0. This single case supports using a fixed filter with bound values; it is not an exhaustive injection test.
In practice: Use --arg for strings and --argjson for already validated JSON instead of concatenating data into filter source.
Observed in this evaluation · low severity under stated conditions
Exit status needs deliberate handling
The -e selection with no result returned 4, while malformed JSON returned 5 with a parse error. Ignoring these statuses can let empty or invalid data continue through automation.
In practice: Check the exit status before downstream actions, and define what an empty result means for the task.
Version, environment and fixture
- Version or deployment
- jq-1.8.2
- Tested target
- https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-windows-amd64.exe
- Artifact identity
- SHA-256 a6fc67fedaf9128a3309a1e2ebb8b986aeccf70122ee46d2cb4849e423f0c627 of the downloaded executable. Recorded to identify the tested artifact; no independent signature or provenance audit was performed.
- Environment and fixture
- Windows 11 x64; Python 3.12.10 harness. Raw timestamps use UTC.
- Fresh per-tool home, config, cache and temporary directories. Child environments used allowlisted OS/runtime paths without inherited account credentials. Only synthetic local files were used.
- Configuration isolation is a test control, not an operating-system sandbox.
Checks and results
5 recorded checks. Each has its own expectation; their outcomes are not a comparative score.
Pinned binary versionMet expectation
- Method
Command argument array: ["jq", "--version"].- Expected
- Print jq-1.8.2.
- Observed
- Exit 0. jq-1.8.2
Select records and fieldsMet expectation
- Method
Create items.json containing [{"id":1,"owner":"Ada","status":"open"},{"id":2,"owner":"Bo","status":"closed"},{"id":3,"owner":"Cy","status":"open"}]. Command argument array: ["jq", "-c", "[.[] | select(.status == \"open\") | {id,owner}]", "items.json"].- Expected
- Return the two open records with id and owner only.
- Observed
- Exit 0. [{"id":1,"owner":"Ada"},{"id":3,"owner":"Cy"}]
Keep filter-looking input as dataMet expectation
- Method
Command argument array: ["jq", "-n", "--arg", "value", "x\" | error(\"injected\") | \"", "{value:$value}"].- Expected
- Preserve the --arg value literally without evaluating its embedded filter syntax.
- Observed
- Exit 0. { "value": "x\" | error(\"injected\") | \"" }
Signal an empty resultMet expectation
- Method
Create items.json containing [{"id":1,"owner":"Ada","status":"open"},{"id":2,"owner":"Bo","status":"closed"},{"id":3,"owner":"Cy","status":"open"}]. Command argument array: ["jq", "-e", ".[] | select(.id == 99)", "items.json"].- Expected
- Return exit 4 with no selected values.
- Observed
- Exit 4. Standard output and standard error were empty.
Reject malformed JSONMet expectation
- Method
Create bad.json with the exact bytes {"unfinished": and no closing value. Command argument array: ["jq", ".", "bad.json"].- Expected
- Return a parse error and nonzero exit.
- Observed
- Exit 5. jq: parse error: Unfinished JSON term at EOF at line 1, column 14
Practical caveats
- The tested filters only read synthetic files or command arguments and wrote standard output.
- The fixture demonstrates specific filter and exit behavior; it does not validate all input schemas or shells.
What this evaluation does not establish
- Large or adversarial JSON, parser fuzzing, performance and every shell quoting or filter-injection case.
- Production API schemas, confidential datasets and downstream commands that consume generated output.
Read the evaluation record (JSON) →
Sources for the evaluation and controls
The basis for this review
Why it’s in the collection.
Adds a broadly useful JSON transformation step that can turn other CLI outputs into a small, reviewable result. Placed before the more specialized additions for its simple local setup and clear input/output boundary. The original catalog order is preserved; this is an editorial position, not a measured adoption or security rank.
The number is an editorial starting order within the cli tools collection. It does not measure popularity, speed, reliability or safety.
Why we added it
Adds a small JSON query/transform tool useful for API outputs and repeatable evidence extraction.
Selection evidence checked .
- Repository interest
- 35,854 GitHub stars at this snapshot ↗
Interest in the source repository; not a count of verified users or installations.
- Repository activity
- Last push reported by GitHub: . A push can include documentation or maintenance; it does not establish a new stable release.
- Release signal
- jq-1.8.2 ↗ · published . This selection signal can differ from the exact runtime tested above.
- A single dated repository-interest/release snapshot; not measured adoption, growth, effectiveness or security.
- Repository interest and release activity do not establish reliability, model quality or safety. The evaluation names the exact version and conditions tested.
What we reviewed
- Official documentation, repository, license and release identity
- Practical access boundaries and a separate bounded runtime evaluation
The evaluation above lists the current runtime coverage and untested behavior.
Reviewed Oct 18, 2026. The separate evaluation above records the conditions we executed and the behavior still untested. Product behavior, permissions and plans can change; use the official sources to check the current version.
Follow the evidence
Official sources.
- jq manual and argument handling ↗jqlang.org
- Official downloads ↗jqlang.org
- jq repository ↗github.com
- License and third-party notices ↗github.com