From e3348913075fbaecce8ac4f2124c0fc0465a792f Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Wed, 22 Apr 2026 08:42:26 -0700
Subject: [PATCH] docs(readme): document --json as the supported
 machine-readable output

Issue #3227 asked for a note in the README that default human-readable
CLI output is not a stable API and that scripts should use --json
instead. Maintainers agreed on the thread and invited a PR.

Add a new "Machine-readable output" section between "Using with CI
Systems" and "Using as a Module" with:

- a short explanation of why default stdout is not stable / parsable,
- a worked example pair showing the same hosting:channel:list call
  with and without --json,
- a pointer to the "Using as a Module" section for callers that need
  thrown errors instead of exit codes.

Pure docs change: prettier --check passes, no runtime or test changes.
---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 4cea658103b..c0ca671b71f 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,31 @@ Complete the following steps to run Firebase commands in a CI environment. Find
 
 To disable access for the service account, [find the service account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts) for your project in the Google Cloud Console, and then either remove the key, or disable or delete the service account.
 
+## Machine-readable output
+
+By default, the Firebase CLI prints human-readable output to `stdout`. That
+output is **not** part of the CLI's API — it may change at any time — so
+scripts and CI pipelines should not parse it directly.
+
+For scripting and automation, pass the `--json` flag to any command. With
+`--json`:
+
+- `stdout` receives a single JSON document describing the command's
+  result — parsable regardless of exit code.
+- The shape is stable across versions and intended for programmatic use.
+
+```bash
+# Human output (default) — do not parse this in scripts
+$ firebase hosting:channel:list --project my-project
+
+# Machine output — safe to parse in CI
+$ firebase hosting:channel:list --project my-project --json | jq '.result.channels[].name'
+```
+
+If `--json` isn't enough for your use case (e.g. you need to catch thrown
+errors rather than inspect an exit code), see [Using as a
+Module](#using-as-a-module) below.
+
 ## Using as a Module
 
 The Firebase CLI can also be used programmatically as a standard Node module.