Skip to content

Tracking: family-wide JSON-on-resource-reads policy alignment #31

Description

@rianjs

Tracking issue. Family-wide migration from "JSON on every resource-read" to the §2 stance: JSON is reserved for round-trip payloads (e.g., automation export) and control-plane envelopes (e.g., set-credential --json).

Why: §2 of docs/output-and-rendering.md — agent-first text output is the primary surface; JSON on resource reads gives agents two consumption paths to maintain (text + JSON) and incentivizes them to pick the verbose one. Only jtk holds this line today.

Affected CLIs (need child issues per CLI):

  • slck — global -o json exposes JSON on every resource read
  • sfdc — global -o json exposes JSON on every resource read
  • nrq — global -o json exposes JSON on every resource read
  • cfl — global -o json exposes JSON on every resource read (part of atlassian-cli true-ups parent issue)
  • gro — per-command --json flags (e.g., gro drive drives --json)

Reference: jtk reserves JSON for automation export only — no global -o json flag registered.

Out of scope: Control-plane envelopes (set-credential --json, config show --json per §1.8 of working-with-secrets.md) are not "resource reads" and are NOT being removed. The §2 line is about reads-of-application-resources only.

Breaking change: Removing -o json will break downstream scripts. Needs deprecation cycle (warn-then-remove) across all 5 affected CLIs.

Source: docs/output-and-rendering.md §10, divergence catalog (PR #28 / commit e4d59c6).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions