tool-jq

name	tool-jq
description	Use jq to parse, filter, and transform JSON in shell pipelines. Trigger when structured JSON extraction or reshaping is needed.

tool-jq

When To Use

• Extract fields from API responses and config outputs.
• Transform nested JSON into concise pipeline-friendly structures.
• Validate JSON shape and enforce required keys in scripts.

Trusted Commands

jq . file.json
jq '.fieldName' file.json
jq '{id, name, status}' file.json
jq '[.items[] | {id, name}]' file.json
jq '.items | length' file.json
jq '.items[] | select(.status == "active")' file.json
jq '.name // "unknown"' file.json
jq -r '.name' file.json
jq -c '.items[]' file.json
jq -e '.token' file.json

Safe Defaults

• Start with jq . to confirm valid JSON.
• Use -r for raw strings passed to other commands.
• Use -e where null/false must fail a pipeline step.

Common Pitfalls

• Missing keys return null instead of raising an error.
• Quoted JSON strings are not suitable when raw output is required.
• Large one-liner filters become brittle without iterative checks.

Output Interpretation

• Pretty JSON by default; use -c for compact JSON lines.
• -e returns non-zero on null/false, useful for guard conditions.

Why It Matters For Agents

• jq is the standard adapter between JSON output and shell automation.
• It reduces custom parser code and keeps pipelines deterministic.

Repo Conventions

• Prefer jq over ad-hoc JSON parsing scripts.
• Keep filters readable and scoped to required fields.

Trigger Examples

• Should trigger: "Extract tool names from this JSON report."
• Should trigger: "Convert API JSON into a compact table-friendly shape."
• Should not trigger: "Lint shell scripts for quoting errors."