CLI workflow
Transform JSON Reliably with a CLI
Inspect the input shape, build a deterministic jq filter, validate the result, and only then replace a file if needed.
Prepare tools, authentication, and evidence first
Install the recommended tools, confirm minimum permissions, and keep compatibility separate from real execution records.
Copy or download this workflow Skill
The Skill includes input and output contracts, recommended tools, approval points, rollback, and evidence boundaries. Review it against the active environment before saving.
---
name: transform-json-workflow
description: "Inspect the input shape, build a deterministic jq filter, validate the result, and only then replace a file if needed."
---
# Transform JSON
## Intended outcome
Produce valid JSON with the requested schema while preserving the original input.
## Evidence boundary
- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.
## Recommended tools, installation, and authentication
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
- Install: `brew install jq`
- Authentication: not required for the base operation
- Minimum permissions: No service credential is required; restrict filesystem and network access to the task.
## Input contract
- JSON file or stream
- required output fields
- filtering and sorting rules
- sample records
## Output contract
- jq filter
- validated JSON
- change summary
- optional replacement file
## Safe workflow
1. **Inspect the shape** — Read types and representative keys before writing a filter.
- Input: Source JSON
- Output: Observed schema and edge cases
- Risk: `read-only`
- Command: `jq 'type, (if type == "array" then .[0] else keys end)' input.json`
2. **Transform to a new file** — Run the filter into a temporary output rather than overwriting the source.
- Input: Reviewed jq filter
- Output: Candidate JSON file
- Risk: `local-write`
- Command: `jq '[.items[] | {id, name}]' input.json > output.json`
3. **Validate and compare** — Parse the candidate, check required fields, and compare counts or checksums before replacement.
- Input: Source and candidate files
- Output: Validation and change summary
- Risk: `read-only`
- Command: `jq -e 'all(.[]; has("id") and has("name"))' output.json`
## Ask before proceeding
- Replacing an existing file
- Dropping fields not named in the request
- Sending local JSON to a remote service
## Rollback
- Keep the source file unchanged until validation passes
- Write atomically from a validated temporary file
- Restore the previous file from version control or backup
## Official sources
- [jq manual](https://jqlang.github.io/jq/manual/) — Official filters, input modes, exit status, and JSON transformation reference.
Outcome, inputs, and outputs
Define the result and evidence before the agent selects a command.
Transform JSON Reliably with a CLI: safe workflow
Run each step inside its stated boundary and verify the output before continuing.
Approval points and rollback
Pause at the listed decision points and keep recovery instructions beside the action.
CLI, MCP, or API?
Choose the interface by execution location, identity, output contract, and permission boundary.
Recommended approach
Use jq locally and make overwriting a separate, reviewable step.
Official evidence and references
Use these primary or upstream sources to verify current command behavior before acting.