elastic / elastic/cli

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

Open
#316 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
41
Forks
24
Avg merge
1d 3h
Merged PRs (30d)
56

Description

## 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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.