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.

[ilyazub]

Opus 5.5 Max rebase, fixes and tests:

Thanks @strzibny! Rebased onto main 993b281 with 3 fixes on top: debug-option moved from f11a754 to 8e98b0c. If you have no unpushed commits on it, git fetch origin && git switch debug-option && git reset --keep origin/debug-option updates your branch.

Your 4 commits keep your authorship. f11a754 was a merge, so its changes (the JSON lines and the port to #17's client) are now a plain commit, 0caec01, whose tree equals f11a754 merged into main, with root.go's one conflict taking your --debug lines and main's new exit-130 wording.

1. b606c29: the trace could print the API key, from a redirect's Location, a URL-encoded proxy login redirect, or a header named after the key: 5 of 6 test cases before, 0 now.
2. e80918f: the timeline compared this machine's clock with SerpApi's. In a test with the clock 6s fast, a fresh 9s search read as "cached result … the +9.5s wait was network round trip only". The verdicts now say they assume synced clocks.
3. 8e98b0c: the timeout error lost main's google_ai_mode/no_cache hint and suggested --debug with --debug on. On a timeout the trace can't tell slow processing from a stuck response, so the hint is back, and the --debug hint shows only while it's off.

go test -race ./... passes on each commit here, with no key; the live e2e tests run in CI on this push.

Whichever of this and #14 merges second won't build until #14's do takes the tracer (undefined: tr ×5), and logRequest has to print req.Method, or uploads are traced as GETs. git also marks the start of the timeout advice: close this PR's debugHint block before #14's /image branch, and append the hint to the upload's message too.

Label release:minor. To ship this and #14 as one v0.4.0, label the first merge release:skip and the second release:minor.

GPT-6 Astra Max advised.