RFC: CLI and Desktop App version alignment

[samuv]

Summary

Establishes how ToolHive Studio (Desktop) manages CLI installation to guarantee version compatibility.

Problem

• Desktop UI is 1:1 coupled to CLI's thv serve API (currently in alpha)
• Users can install CLI independently (Homebrew, direct download)
• Version mismatches cause API errors and broken UI
• No coordination exists between CLI and Desktop installations

Solution

Desktop owns CLI installation — regardless of how Desktop was installed:

• Bundles CLI binary inside the app (no network required)
• Installs to ~/.toolhive/bin on first launch
• Auto-configures PATH (shadows existing installations)
• Validates version on every launch
• Provides conflict dialog when external CLI detected

Why This Is Needed (Even After Alpha)

This infrastructure is required regardless of API maturity:

1. Now: Exact version pinning (alpha API, no compatibility guarantees)
2. Future: Relax to minimum version constraints once backward-compatibility policy exists
3. Always: Users need a mechanism to get CLI when installing Desktop

Learned from Docker Desktop

Problem	Docker	ToolHive
Naming	Same name causes conflicts	Distinct: toolhive vs toolhive-studio
PATH setup	Manual for "User" mode	Auto-configured
Coexistence	Hard failures	Shadows in PATH, no conflicts
Admin required	Yes for "System" mode	Never

Key Design Decisions

• User-space installation (no elevation required)
• Atomic upgrades with checksum verification
• Distinct package names to avoid Homebrew conflicts
• Foundation for future API version negotiation

[peppescg]

My 2c the only way to be sure it is not possible to break stuff is to always have API backward compatibility, and in case of breaking changes block the toolhive release until UI is not handling the breaking changes (For avoiding this it would be important the planning phase, checking all possibles issues with UI, in order to avoid see this issue 1h before a release)

[JAORMX]

My 2c the only way to be sure it is not possible to break stuff is to always have API backward compatibility, and in case of breaking changes block the toolhive release until UI is not handling the breaking changes (For avoiding this it would be important the planning phase, checking all possibles issues with UI, in order to avoid see this issue 1h before a release)

I agree, we need to have API assurances and we should aim for that too. Maybe it's not part of this particular proposal, but this proposal should depend on that.