Parent: backend#830 (RFC-0001 epic) · RFC: §13, §14 R11, Appendix C.1 · Phase 1 — CLI
Related: backend#888 (the backend min-version + 426 enforcement half of R11), cli#83 (internal/api client this header lives on)
Why
R11: three repos on different cadences + a new contract = undefined failures on skew. The CLI must announce its version on every request and degrade cleanly when the backend says it's too old — a clear "upgrade required," not a stack trace.
Scope
Per Appendix C.1:
- Send
User-Agent: tracebloc-cli/<ver> (<os>/<arch>) on every backend request (set it on the shared internal/api client from cli#83). - Handle a
426 Upgrade Required response anywhere in the flow: parse { error: "upgrade_required", min_version }, print an actionable "your CLI is too old — upgrade to ≥ <min_version>: <how>" message, and exit non-zero with no stack trace.
Acceptance
- Every CLI → backend request carries the
User-Agent: tracebloc-cli/<ver> (<os>/<arch>) header. - A
426 from any endpoint → the upgrade message + clean non-zero exit (no panic/trace), in both interactive and --plain/non-TTY modes. - Normal (non-426) flows are unchanged.
Notes
Pairs with backend#888 (MIN_SUPPORTED_CLI_VERSION + 426). The header alone is a no-op until the backend enforces, but it's cheap and lands the contract from the client side.
Work Type: Feature · Squad: DevEx · Area: SDK (CLI) · Priority: P1
Parent: backend#830 (RFC-0001 epic) · RFC: §13, §14 R11, Appendix C.1 · Phase 1 — CLI
Related: backend#888 (the backend min-version + 426 enforcement half of R11), cli#83 (
internal/apiclient this header lives on)Why
R11: three repos on different cadences + a new contract = undefined failures on skew. The CLI must announce its version on every request and degrade cleanly when the backend says it's too old — a clear "upgrade required," not a stack trace.
Scope
Per Appendix C.1:
User-Agent: tracebloc-cli/<ver> (<os>/<arch>)on every backend request (set it on the sharedinternal/apiclient from cli#83).426 Upgrade Requiredresponse anywhere in the flow: parse{ error: "upgrade_required", min_version }, print an actionable "your CLI is too old — upgrade to ≥<min_version>:<how>" message, and exit non-zero with no stack trace.Acceptance
User-Agent: tracebloc-cli/<ver> (<os>/<arch>)header.426from any endpoint → the upgrade message + clean non-zero exit (no panic/trace), in both interactive and--plain/non-TTY modes.Notes
Pairs with backend#888 (
MIN_SUPPORTED_CLI_VERSION+ 426). The header alone is a no-op until the backend enforces, but it's cheap and lands the contract from the client side.Work Type: Feature · Squad: DevEx · Area: SDK (CLI) · Priority: P1