Skip to content

Add --format=json for structured CI output #177

@xaaha

Description

@xaaha

Problem

CI pipelines that consume hulak run results need to grep/regex the human-readable output to figure out what happened — fragile and locale-sensitive. A structured machine-readable format would let CI scripts pass/fail cleanly.

Proposal

New flag --format=<text|json> (default text, current behavior).

With `--format=json`, every per-file outcome emits one JSON object on stdout, one per line (NDJSON / JSON Lines):

{"file":"requests/get_user.hk.yaml","ok":true,"status":200,"duration_ms":142,"attempts":1}
{"file":"requests/create_user.hk.yaml","ok":false,"status":500,"duration_ms":1203,"attempts":3,"error":"unexpected status"}

After all files: a final summary line:

{"summary":true,"total":2,"succeeded":1,"failed":1,"duration_ms":1345}

Constraints

  • Pairs naturally with --quiet--format=json --quiet suppresses any stderr noise so stdout is clean JSONL only.
  • Still emits errors to stderr in human-readable form unless --quiet is also set; CI typically wants both stdout (structured) and stderr (logs).
  • The response body itself does NOT go in the JSON object (could be huge / binary). {filename}_response.json continues to be written as today; the JSON line just includes the file path so CI can read it back if needed.
  • Keep the schema additive — never remove fields, only add. Document the schema in docs/cli.md.

Done when

  • --format=json validated against text; unknown values error.
  • Per-file JSONL line on stdout for every processed file.
  • Summary line at the end.
  • Schema documented.

Parent: #154
Related: verbosity flags ticket (--quiet pairs with this)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestepic: ergonomicsIssues that belong to the authoring and discovery ergonomics epic

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions