Skip to content

feat(cli): add --debug flag and ELASTIC_DEBUG env var for HTTP request logging #316

Description

@margaretjgu

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions