No global machine-readable output flag

[armamini]

The issue

Right now the CLI only prints human-friendly text. That's great when you're
reading it in a terminal, but painful the moment you try to automate anything.

If I want a pipeline to fail on a bad config, I run circleci config validate
and get a paragraph of text back. To act on it in a script, I have to grep the
output and hope the wording never changes. It does change, and then my
automation quietly breaks. The exit code tells me pass or fail, but not what
went wrong in a way a machine can read.

What I'd like

A single global flag: -o, --output json (default stays text, so nothing
breaks). In JSON mode, commands return a predictable shape like:

{
  "status": "error",
  "errors": [
    { "code": "invalid_key", "message": "unexpected key 'jobz'", "path": ".jobz", "line": 4 }
  ],
  "warnings": []
}

Nice-to-have: honor a CIRCLECI_CLI_OUTPUT=json env var so CI can default to it
without adding the flag everywhere.

Commands it should cover

config validate, config pack, orb validate, orb list, context list,
and the runner commands.

Why it matters

It turns config validate into a reliable CI gate and lets dashboards or
ChatOps surface line-level errors without brittle text parsing. Small change,
big quality-of-life win for anyone running the CLI in automation.

BR,
Arman.

[pete-woods]

Triage: partly shipped in the v1 CLI — narrowing this to what is left

Thanks Arman, this was one of the founding requirements of the v1 rewrite (main; v0 is
the legacy CLI that ships today), and most of it is in.

Done. Every data-returning command takes --json, with its fields enumerated in
--help so you can see the shape without running it. That is a hard rule for the v1
codebase, not a per-command decision, so the coverage list in your report —
config validate, config pack, orb validate, orb list, context list, the runner
commands — is covered, along with everything else. Streams are separated properly too:
data on stdout, progress and diagnostics on stderr, so circleci ... --json | jq is safe.

Errors already carry structure internally — every one has a code, title, message,
suggestions and a docs reference, and exits with a meaningful code (2 bad arguments,
3 auth, 4 API, 5 not found, 7 validation failure, 8 timeout). So config validate as a CI
gate works on the exit code today without grepping prose.

Still open, and what I am keeping this issue for:

1. Structured errors in JSON mode. The error type has the fields; --json does not yet
   render them. Your example shape is close to what we would emit — status, errors[]
   with code/message, warnings[] — with the caveat that per-error path and line
   come from the config-compilation service, so line-level detail depends on what it
   returns rather than on the CLI alone.
2. -o, --output json as a global alias for --json. Worth doing for the reason you
   give: one flag you can pass to anything, rather than remembering which commands have it.
3. An environment variable. CIRCLECI_CLI_OUTPUT in your report — v1 uses the
   CIRCLE_ prefix (CIRCLE_TOKEN, CIRCLE_HOST, CIRCLE_NO_COLOR), so this would be
   CIRCLE_OUTPUT=json, documented in circleci help environment.

Of those, (1) is the one that unblocks the dashboards-and-ChatOps case you describe; (2)
and (3) are ergonomics.

[armamini]

Thanks @pete-woods
I’m excited to see an amazing version ahead!
BR