Summary
There is currently no way to see what HTTP request the CLI is actually sending when a command fails unexpectedly. A --debug flag (or ELASTIC_DEBUG=1 env var) that logs outgoing requests and responses is the first thing a developer reaches for when troubleshooting.
Proposed UX
$ elastic es cluster health --debug
> GET http://localhost:9200/_cluster/health
> x-elastic-client-meta: ...
> authorization: (redacted)
< 200 OK
< content-type: application/json
{ "cluster_name": "my-cluster", "status": "green", ... }
Alternatively as an env var:
ELASTIC_DEBUG=1 elastic es cluster health
Both forms should work. The flag takes precedence.
Implementation notes
- Output should go to stderr so it does not interfere with
--json or --output-template piping.
- Credentials must be redacted --
Authorization and X-Api-Key headers should be replaced with (redacted) in debug output. Never print raw secrets.
- Request body should be printed when present (e.g.
--input-file or --body payloads).
- Response body should be printed as-is (it is already non-sensitive by definition of what the CLI returns).
- The debug flag should be a global root-level option (alongside
--json, --config-file) so it applies to all subcommands without needing to be re-declared everywhere.
- All three HTTP clients (
EsClient, KibanaClient, CloudClient in src/lib/) should honour it -- consider a shared debugLogger utility that each client calls after each request/response cycle.
Acceptance criteria
elastic es cluster health --debug prints request method, URL, sanitised headers, and response status to stderr
ELASTIC_DEBUG=1 elastic es cluster health produces the same output
- Raw credential values never appear in debug output
--json output is unaffected (debug goes to stderr, result goes to stdout)
- Works for ES, Kibana, and Cloud API calls
Summary
There is currently no way to see what HTTP request the CLI is actually sending when a command fails unexpectedly. A
--debugflag (orELASTIC_DEBUG=1env var) that logs outgoing requests and responses is the first thing a developer reaches for when troubleshooting.Proposed UX
Alternatively as an env var:
Both forms should work. The flag takes precedence.
Implementation notes
--jsonor--output-templatepiping.AuthorizationandX-Api-Keyheaders should be replaced with(redacted)in debug output. Never print raw secrets.--input-fileor--bodypayloads).--json,--config-file) so it applies to all subcommands without needing to be re-declared everywhere.EsClient,KibanaClient,CloudClientinsrc/lib/) should honour it -- consider a shareddebugLoggerutility that each client calls after each request/response cycle.Acceptance criteria
elastic es cluster health --debugprints request method, URL, sanitised headers, and response status to stderrELASTIC_DEBUG=1 elastic es cluster healthproduces the same output--jsonoutput is unaffected (debug goes to stderr, result goes to stdout)