Skip to content

feat: add --json / machine-readable output to status, validate, and diff #23

@HelenGreul

Description

@HelenGreul

Problem or motivation

poly status, poly diff, and poly validate all output human-formatted Rich console output. There is no way to consume this output programmatically — in CI pipelines, editor integrations, or shell scripts — without fragile text parsing.

For example, a CI step that wants to fail if there are merge conflicts must currently scrape the colorized terminal output of poly status. Similarly, there is no clean way to surface poly validate errors inside an editor extension.

Every mature platform CLI (gh, kubectl, Heroku CLI, Salesforce CLI) offers a --json or --porcelain flag for exactly this reason.

Proposed solution

Add a --json flag to at least the three highest-value commands:

poly status --json
# → {"conflicts": [], "new": ["flows/foo.yaml"], "modified": [], "deleted": [], "branch": "main"}

poly validate --json
# → {"valid": false, "errors": [{"file": "flows/foo.yaml", "message": "..."}]}

poly diff --json
# → {"files": [{"path": "flows/foo.yaml", "hunks": [...]}]}

When --json is passed, skip all Rich formatting and write a single JSON object to stdout. Errors still go to stderr.

Alternatives considered

--porcelain (git-style stable plain-text format) would also work, but JSON is easier to consume without a custom parser and is the current industry standard for CLI machine output.

Scope

CLI commands

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