[CON-906] Correct the CLI and SDK references against the live product

[0xsergen]

Part of the CON-901 reference audit. Covers CON-906: cli-reference.md and sdk-reference.md.

Every claim in both files was executed against the live account. 16 defects found and fixed.

Method

• qn 0.6.0 CLI, walked recursively through --help. 126 leaf commands enumerated. All 126 are covered by the reference. 0 missing.
• @quicknode/sdk 3.8.2, installed from the registry. 12 scripts written and run. Final result 12 pass, 0 fail.
• All chain reads on ethereum-mainnet. No resource was created and nothing was billed.

What was wrong

#	Where	Claimed	Actual
1	SDK import	Quicknode	The class is QuicknodeSdk. Quicknode is not an export
2	SDK construction	new Quicknode({ apiKey })	QuicknodeSdk.fromEnv(), reading QN_SDK__API_KEY
3	SDK testFilter	dataset: "block"	The enum member StreamDataset.Block. A raw string is rejected
4	SDK errors	one error type	A typed tree: QuicknodeError with ConfigError, HttpError, TimeoutError, ConnectionError, ApiError, DecodeError, RpcError, PaymentError
5	qn kv list wording	"ordered string collections"	Lexicographically sorted. Insert zebra, mango, apple, read back apple, mango, zebra
6	qn stream test-filter output	not documented	result is a JSON string. It needs a second decode before you can read the filter's return value
7	qn rpc call -o json	not documented	Prints the JSON-RPC result unwrapped. There is no jsonrpc, id, or result field, so .result is undefined
8	piped output default	piped output is always json	qn rpc list-networks prints a bare newline-separated list even when piped. With -o json it gives {networks: [...]}, not a data envelope

The full list, with the exact invocation and exit code for each, is in the audit findings file.

The silent one

Item 6 is the one to read twice. It is a response-shape defect (class 1), and it fails silently. qn stream test-filter exits 0 and prints {"result": "...", "logs": []}. A caller that checks the exit code, or that reads .result without decoding it, cannot tell a working filter from a broken one. The reference now says so, and the Test: line asserts it.

Item 8 corrects a claim this PR itself made

Worth calling out, because it is the same mistake the audit exists to catch.

An earlier commit on this branch added a Test: line saying piped output defaults to json, "so a script never has to pass -o json". Then I piped four commands to head -c 1:

Command piped	First byte
qn endpoint list	{
qn chain list	{
qn kv set list	{
qn rpc list-networks	0

That last one is the 0 of 0g-galileo. The rule holds for three of four and not the fourth. A script that pipes qn rpc list-networks and parses JSON fails. The Test: line now names all four commands and the exception, and the prose above it says to pass -o json explicitly for that command.

The qn CLI has seven confirmed -o json shapes and no single envelope. Five are in kv-reference.md (see #13) and two are here. Read the shape for the command you ran. Never assume data.

Test: lines

11 added: 8 in cli-reference.md, 3 in sdk-reference.md. Each names the network and the block, then one value a reader can compare against their own run. Where an example touches no chain data it asserts the observable result instead.

Two assertions are deliberately written as shapes, not counts, because both drift: the network-key list names its first and last entry rather than gating on 132, and the block-object assertion names the missing envelope rather than a field count.

Coverage is 11 of 45 runnable blocks, and that is deliberate for 30 of the 34. Full accounting:

Reason a block has no Test: line	Count
Creates a billed resource, or moves funds: paid RPC x402 and MPP, endpoint create, stream create, webhook creation, sql query	17
Account-scoped, so no value another reader can compare against: auth whoami, endpoint list/get, endpoint security, team ×3, account overview	9
Environment-specific: installation, auth login/logout	4
Real remaining work	4

The 4 are all SDK blocks: Admin API ×2, Webhooks, Key-Value Store. They are assertable, but running them needs QN_SDK__API_KEY, which was not exported in the session that added these lines. The three free RPC variants that were open earlier are now done, and closing them is what turned up items 7 and 8.

The Test: line assumes a pinned block and a value every reader can reproduce. That fits a filter reference, where streams-reference.md reaches 13 of 19. It mostly does not fit a CLI reference, because most CLI examples are account-scoped. Asserting this account's endpoint count helps no other reader, so those examples get nothing rather than something invented.

Also documented

Every delete command needs --yes when no terminal is attached. Without it the command exits non-zero and deletes nothing. Found while scripting this audit's own resource cleanup.

Checked and found correct, so not changed: qn kv list list is the canonical subcommand with ls as its alias. It is not a typo for ls.

Not covered, and why

• qn sql query carries a per-query charge and does not auto-retry. Verified for help text and argument parsing only.
• qn endpoint create and the stream create paths create billed resources. Not executed.

Version bump

None here. The build-web3 patch bump to 1.0.3 lands in the CON-905 PR, which is the last of the three to merge. Three PRs each editing the same four manifests would conflict.

Related: CON-902 and CON-905 PRs cover the other three files from the same audit pass.