[CLI] Make serpapi predictable for agents and scripts, and safe on terminals

[ilyazub]

Opus 5.5 Max wrote this:
Stop serpapi from echoing the API key or passing escape sequences from results to the terminal. Reject malformed commands before they reach the API, and keep fetched pages when Ctrl-C stops --all-pages. Measured against a local fake SerpApi, not production. Resolves #10.

On main, each of these can break an unattended run by a script or an AI agent. output=md also fails with the error in #10, and releases build with go.mod's go1.25.0, which has known standard-library vulnerabilities.

The fix separates errors from results and checks syntax and flag combinations before any request. Results go to stdout, escaped on a terminal and byte-exact in a pipe. Each error is one JSON line on stderr, and exit 2 means the command is wrong. --all-pages streams its pages and keeps them on Ctrl-C. Releases build with the latest patched Go.

Main against this PR: 120 commands on the fake SerpApi, plus terminal, memory and release-build probes.

	main 6152d44	this PR 982116a
API key echoed	2 commands	0
API control bytes on a real terminal	4 of 6 probes	0 of 6
Commands now rejected with exit 2	13 of 13 sent a request; 7 then exited 0	0 of 13 sent one
Ctrl-C on page 4 of --all-pages	nothing printed	pages 1–3, exit 130
output=md (#10)	exit 1	Markdown, exit 0
Peak RSS, 100 × 1 MiB pages, median (range) of 11	742 (660–893) MiB	185 (178–191) MiB
govulncheck, darwin/arm64, release-style build	57	0
Control: main against itself	0 of 120 commands differ; 735 MiB

• 0.07 s slower on 100 piped pages: median 0.70 → 0.77 s (n=11; main against itself 0.70 vs 0.68 s). The large-result warning's sizing pass costs it: without that pass, 0.66 s. With --jq, 0.78 → 0.54 s.
• Lost later results: --all-pages stops at the first page --fields matches nothing on. A misspelled --fields path over endless pages sent 100 requests on main and printed {}; here it sends 1. But results that start later are lost: on the fake SerpApi, page 5's 2 results became {} and a warning.
• Merge risk: Add initial output=md support #11, Add support for /image api #14 and Add --debug option #16 (@strzibny) conflict in 5, 4 and 3 files; whichever lands second rebases. This PR supersedes Add initial output=md support #11's output=md. Add --debug option #16's [debug] lines would fit the stderr contract as JSON lines when stderr isn't a terminal.
• CI on 982116a: both Linux test jobs passed, and e2e ran the 10 live tests: 12 PASS, 0 SKIP (run 38312832327). Not covered: Windows only compiles.

To merge, accept the --fields trade-off; the rest is measured above. Merging releases nothing: a maintainer tags v0.3.0 later, once CI passes with no skipped live test.

What else scripts may notice

• The 13 newly rejected commands: q= plus bare words; no parameters; the key as key, apikey, serpapi_key or serp_api_key; --fields outside search; a --jq syntax error, input or debug; --max-pages 0; --all-pages with async=true or output=md; --jq with output=md; an unknown output=; locations without a query.
• Bare words join into one q: engine=google coffee shops sends q=coffee shops (main: q=shops).
• Now work: output=md in any case, output=html, archive ID output=md, serpapi version, SERPAPI_API_KEY, login --api-key, jq halt, and durations such as --timeout 2s (main: exit 1 or 2).
• --help lists exit codes 1, 2 and 130; README's "For AI agents" also lists 0. Error lines carry the HTTP status when there is one.
• --all-pages adds no_cache, zero_trace and output to every page; main sent only what serpapi_pagination.next held. A 200 with an error on a later page is a warning, exit 0 (main: exit 1). When a later page fails, or next isn't a URL, the pages so far print before the exit 1.
• A JSON array body is exit 1 api_error (main: exit 0). A padded SERPAPI_KEY is trimmed.
• --fields adds error to json_restrictor; --fields ,, sends none (main sent ,, and printed {}).
• serpapi with no command prints its usage only on a terminal, on stderr (main: stdout); stderr always gets the JSON error.
• Unchanged: a --jq that fails on the response, such as tonumber on a title, exits 2 after its search.

Checks, reviews, release and rollback

Opus 5.5 Max checks on 982116a (macOS arm64, fake SerpApi on localhost, base main 6152d44):

each of the 26 commits   go vet, staticcheck, go test -race ./pkg/... pass alone; gofmt fails
                         only before [Style], on main's 3 unformatted files
go1.27.2 and go1.25.0    go test -race ./...: 299 passed, 10 skipped (live, no key), 0 failed
-race, 20 times          pkg/cmd, pkg/output, pkg/api: 4,580 runs, 0 failures
fuzz, 8 targets x 20 s   0 failures
terminal probes          5 search outputs and the login prompt
interleaved A/B          11 rounds, rotated; startup 24.2 ms on both (n=50; main vs main 23.5)
govulncheck              main with go1.25.0: 57 darwin/arm64, 58 linux/amd64; this PR with
                         go1.27.2: 0 in all 5 targets (DB 2026-10-08)
goreleaser 2.18.3        release --skip=publish, local tag only: 5 archives, checksums 5/5,
                         formula test 5/5

Reviews: GPT-5.6 Sol Max (security and the plan); GPT-6 Astra Max and Fable 5.1 Max (earlier drafts of this description; their edits are applied).

After merge, a maintainer tags the merge commit as AGENTS.md says and checks the 5 archives, the serpapi-cli 0.3.0 commit in serpapi/homebrew-tap, and brew test serpapi-cli. Kill criterion: a script-visible change not listed here. Rollback: revert the tap's formula commit, and release v0.3.1 with retract v0.3.0 in go.mod. Review commit by commit; the bottom 3, up to 1bc0863 (release workflow and AGENTS.md), can go first as their own PR if a release is due sooner.