Add --debug option

[strzibny]

Let's add --debug option for better debugging logs when customers face something unexpected regarding connections and timeouts.

Debug mode adds tracing for each request to stderr with wall-clock and elapsed timestamps; DNS, TCP connect (local -> remote address), TLS handshake, time to first byte, response status and headers, and body size.

For searches, we also correlate the server's search_metadata timestamps with the client timeline and flag whether a long wait happened before the search was created, during processing, or after processing finished.

[ilyazub]

Opus 5.5 Max wrote this:
#17 is merged (7acfb80); against main this PR now conflicts in 3 files (README.md, pkg/api/client.go, pkg/cmd/root.go). On main, errors and warnings go to stderr as one JSON line each, and in a 120-command matrix every stderr line of a non-interactive run was JSON; scripts and agents parse stderr line by line, so plain [debug] lines would break that. Printing them as JSON lines, such as {"debug":{...}}, when stderr isn't a terminal, and as plain text on one, keeps it; login and the no-command usage already split this way.

[strzibny]

@ilyazub That's a good catch. I tried to address it.

Every non-interactive stderr line stays a JSON object. When stderr is not a terminal, each --debug trace line is:

{"debug":{"at":"2026-10-13T10:12:03.412Z","elapsed":1.234,"event":"...","data":{...}}}

So existing line-by-line parsers for {"error":…} and {"warning":…} keep working, and 2> trace.jsonl produces a parseable file. On a terminal the output stays human-readable: [debug] <time> +<elapsed>s <event>.

[pulkitchowdry]

Thanks for the work on this @strzibny!

I tested the --debug flag including the latest changes related to the json output (for example 2>debug.jsonl) and text output on terminal.

Tested for network errors (including proxy, awaiting headers error), minimal timeout, invalid api key, combining debug with jq, timeout flags and everything looks good to me.