docs(cli): complete the deferred versioned pass for the CLI reference (2.0.x, 2.1.x)

[claudespice]

Summary

docs #2011 corrected the vNext CLI reference and explicitly deferred the versioned snapshots:

Not propagated to versioned_docs/: --output arrived per command across different releases (status in v1.11.x, most others after v1.11.2), so the versioned snapshots diverge command-by-command and need their own pass rather than a copy of this one.

This is that pass, done command-by-command against the release tags. The result: v2.0.1 and v2.1.2 expose the identical CLI surface — same seven global flags, same ten commands with -o/--output, same upgrade/version/refresh/trace flags — so both snapshots carry the same wrong claims and both are fixed here.

What the 2.0.x / 2.1.x docs said vs. what the released binaries do:

Claim in both snapshots	v2.0.1 and v2.1.2
"All commands have a help flag --help or -h" — presented as the complete set of global flags	Seven global = true args: -v/--verbose, --machine, --api-key, --cloud, --cloud-region, --http-endpoint, --tls-root-certificate-file. Several are already used in per-command examples on these same pages (spice chat --cloud --api-key …) without ever being defined.
-o/--output documented only on query, search, login	Also on catalogs, chat, datasets, models, pods, refresh, sql, status, trace, version
spice upgrade [flags], "to the latest release", --help the only flag	spice upgrade [target_version] [flags], "to the latest or specified version", plus -f/--force; a target_version without the leading v is rejected
version, refresh, trace flag lists incomplete	version --cli-only, refresh --refresh-jitter-max, trace --truncate [<length>] (defaults to 80 when passed bare)

Verification

Read the clap derive attributes at each tag — git show <tag>:bin/spice/src/....

Global flags — bin/spice/src/main.rs, struct Cli: seven global = true args at both v2.0.1 and v2.1.2, with the documented details identical at both: alias = "programmatic" on --machine, env = "SPICE_API_KEY" on --api-key, requires = "cloud" on --cloud-region, DEFAULT_CLOUD_REGION = "us-east-1", default_value = "http://127.0.0.1:8090" on --http-endpoint.

-o/--output — enumerated by grepping short = 'o' across bin/spice/src/commands/** at each tag. Identical sets: catalogs, chat, datasets, models, pods, refresh, sql, status, trace, version (plus the already-documented query/mod.rs, search.rs, login/mod.rs, and the undocumented acceleration, workers, cloud). OutputFormat { Table (default), Json }.

upgrade — commands/upgrade.rs at both tags: #[arg(name = "target_version")] version: Option<String>, #[arg(short, long)] force, the !version.starts_with('v') rejection, and about = "Upgrades the Spice CLI and runtime to the latest or specified version".

Per-command flags — version.rs #[arg(long)] cli_only; refresh.rs refresh_jitter_max; trace.rs #[arg(long, default_missing_value = "80")] truncate: Option<usize>. All present at both tags.

Scoped per version — not a flat copy

• tool_use::<tool> trace task names → 2.1.x only. The vNext trace.md paragraph documents both the bare tool_use::<tool> and the tool_use::<server>/<tool> forms. At v2.1.2 both exist (crates/runtime-tools/src/mcp/server.rs:169 and mcp/tool.rs:93). At v2.0.1 only tool_use::<server>/<tool> is emitted (crates/runtime/src/tools/mcp/tool.rs:93; that release's tools/mcp/server.rs records no task span at all), so 2.0.x gets the flag rows without that paragraph.
• version-1.11.x and older are deliberately untouched. v1.11.6 declares a different, smaller set — 5 global = true args, not 7 — so a copy of this table would be wrong there. Those snapshots need their own verified pass; noted rather than guessed.
• version-2.0.x was byte-identical to the pre-change version-2.1.x for all 12 pages, so the two snapshots genuinely shared one set of claims rather than being independently stale.

Grep coverage

$ grep -rln -- "--output" website/versioned_docs/version-2.1.x/cli/reference/   # before
search.md  login.md  query.md

The CLI reference pages are the only place these flags are enumerated: grep -rln 'cli-only\|refresh-jitter-max\|target_version' returns no other page type.

Test plan

• cd website && npm run build passes (onBrokenLinks/onBrokenAnchors/onInlineTags all throw) — 3750 documents, Generated static files in "build". The new refresh.md links (../../reference/duration, ../../features/data-acceleration/data-refresh#refresh-jitter) were confirmed to resolve in both snapshots before building.
• Versioned-docs propagation checked and scoped per release (above)
• Files updated: 24 — 12 under version-2.1.x/cli/reference/, 12 under version-2.0.x/cli/reference/ (matches the diff)

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: claudespice

[github-actions]

🚀 deployed to https://dcc1e0c7.spiceai-org-website.pages.dev

[claudespice]

@copilot review

[github-actions]

🚀 deployed to https://90eed427.spiceai-org-website.pages.dev