---
title: "jq: filter and reshape JSON from the command line"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/cli-jq-json.md
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 
status: reviewed
reviewed_on: 2026-11-02
checked_on: 2026-11-02
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://jqlang.org/manual/
source_license: "project docs; restated, not copied"
license_note: "Steps are our own words from a version run on the Grok Bot box plus the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-11-02
date: 2026-11-02
category: agent-howto
tags: agent-howto, jq, json, cli
checked_on: 2026-11-02
sources:
  - id: S1
    title: "jq Manual"
    publisher: jq project
    url: https://jqlang.org/manual/
    accessed: 2026-11-02
    license: "restated, not copied"
  - id: S2
    title: "Grok Bot box run: jq --version"
    publisher: Grok Bot box
    url: local run, 2026-11-02
    accessed: 2026-11-02
    license: "CC0 1.0 (our own observation)"
---
# jq: filter and reshape JSON from the command line

*Note, . Status: reviewed. Tags: ai, agents, research.*
*Authorship: synthesis by iinventedlight from the cited sources; text drafted with AI assistance (Grok Bot), reviewed by Cole Withington on 2026-11-02.*

# jq: filter and reshape JSON from the command line

## Summary
`jq` reads JSON on stdin or from files and applies a filter. Use `-r` for raw strings and `-e` to make the exit status reflect whether the result is null/false. Read-only by default; it never edits files in place.

*Draft. License: CC0 1.0. Sources: [S1] jq project, "jq Manual"; [S2] Grok Bot box, "Grok Bot box run: jq --version".*

## Agent access
- CLI: yes (`jq`, tested jq-1.7 on the Grok Bot box). MCP connector: none needed. API: none.
- Best route: CLI.
- Permissions: read access to the input; no network.

## Facts
- id: F1
  claim: jq takes a filter expression and input JSON, and prints the result as JSON.
  confidence: high
  date: 2026-11-02
  sources: [S1, S2]
  license: CC0 1.0
  checked_on: 2026-11-02
- id: F2
  claim: `.a[] | select(.v>1) | .n` iterates an array, keeps matching objects and extracts one field; tested on jq-1.7.
  confidence: medium
  date: 2026-11-02
  sources: [S2]
  license: CC0 1.0
  checked_on: 2026-11-02
- id: F3
  claim: `-r` prints strings without JSON quotes, which is the usual choice when piping into other shell tools.
  confidence: high
  date: 2026-11-02
  sources: [S1, S2]
  license: CC0 1.0
  checked_on: 2026-11-02
- id: F4
  claim: `-c` prints compact one-line JSON, handy for logs and line-based tools.
  confidence: high
  date: 2026-11-02
  sources: [S1, S2]
  license: CC0 1.0
  checked_on: 2026-11-02
- id: F5
  claim: With `-e`, jq exits 1 when the last output is null or false; observed exit 1 for a missing key.
  confidence: high
  date: 2026-11-02
  sources: [S1, S2]
  license: CC0 1.0
  checked_on: 2026-11-02
- id: F6
  claim: jq does not modify the input file; write to a new file and rename it if you need an in-place change.
  confidence: medium
  date: 2026-11-02
  sources: [S1]
  license: CC0 1.0
  checked_on: 2026-11-02