docs: add a CLI client guide

[aparajon]

Adds docs/cli.md, a client-side guide for the CLI, and links it from the README. It covers:

• Profiles, the config file, and resolution precedence (profile / endpoint / token)
• The three access models: built-in OIDC login, an authenticating proxy at the edge, and network isolation via port-forward
• The change workflow: plan and apply with example transcripts, including the lock-conflict refusal
• Everyday reads: status, progress, logs, databases, pull, with obfuscated output examples
• Control operations: the escalation ladder (stop → start / cutover / cancel / revert), a verbs table with engine caveats (revert/skip-revert are Vitess-only), and rollback's plan-then-confirm flow
• checks backfill as the GitHub-outage recovery tool, with the dry-run-first rhythm
• Wrapping the CLI: exec-style and Go-embedding wrappers

The "Wrapping the CLI" section documents the --cli-name flag and pkg/cmd/cliname package from #983, so this should merge after it.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds end-user documentation for the SchemaBot CLI client, explaining how operators configure, authenticate, and use the CLI for common workflows and recovery scenarios, and links that guide from the README.

Changes:

• Add a new CLI client guide at docs/cli.md covering configuration/profiles, auth models, plan/apply workflows, reads, controls, and checks backfill.
• Link the new CLI guide from README.md alongside the existing server configuration docs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
README.md	Adds a direct link to the new CLI client guide from the Configuration section.
docs/cli.md	Introduces comprehensive CLI client documentation, including auth models, workflow examples, and wrapper guidance.

Suppressed comments (2)

docs/cli.md:369

• This paragraph names an internal wrapper and company ("At Block… sq schemabot") which makes the guide less reusable and may be considered non-OSS-ready. Consider making this wording generic (the wrapper name can remain an example).

Organizations often front the CLI with their own wrapper command that bakes in the environment — resolving internal endpoints, running SSO, starting a port-forward — so operators never configure any of it by hand. At Block, we build an internal wrapper around the schemabot CLI to target internal deployments, which we denote as `sq schemabot`; other schemabot users may want to follow suit. Two styles work:

docs/cli.md:378

• To keep the docs neutral/OSS-ready, avoid implying a specific internal tool name in the normative description. This line can be phrased generically without changing the example code that follows.

**Embed the Go packages.** For a wrapper with real logic of its own — per-environment routing tables, automatic port-forwards, extra commands — import the command structs and build your own [kong](https://github.com/alecthomas/kong) CLI around them. This is how `sq schemabot` is built:

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.