crabidy/architecture/client-configs.md

Client configs: cbd.toml vs cbd-tui.toml

Problem

cbd (server + TUI in one process) and cbd-tui (standalone terminal client) both originally loaded cbd-tui.toml. On a single machine the common setup is:

• cbd — self-contained, playing on this laptop against its own in-process server (localhost);
• cbd-tui — a remote control pointed at another server (e.g. a Raspberry Pi).

With one shared config file these two uses fight over a single address: point it at the Pi for cbd-tui, and cbd's TUI half also connects to the Pi while its local server runs unused.

Decision

Give each binary its own client config file, with the same option set (address, user, password — the ServerConfig type is shared):

• cbd reads cbd.toml.
• cbd-tui reads cbd-tui.toml.

Both default address to http://127.0.0.1:50051. For cbd that default is the right permanent value — it matches the in-process server's listen address — so cbd needs no config at all. cbd-tui's default is a starting point the user overrides to point at a remote server. The files being separate is the whole point: editing one never moves the other.

The server-side crabidy-server.toml (the [auth] roles) is unrelated and unchanged; this split is purely about the client address/creds.

Alternatives considered

• One file, add a cbd-only override section: still one file to reason about, and the override semantics (which wins?) are murkier than two files with identical shape. Rejected.
• A CLI flag only for cbd: does not persist; the user wants a laptop that "just works" on every start. Rejected (the flag still exists as an override, as for cbd-tui).

Migration

Existing users keep their cbd-tui.toml for cbd-tui. On first run after the change, cbd writes a fresh cbd.toml with localhost defaults; anyone who had customized cbd-tui.toml for cbd's sake (unusual — the default already fit) copies the value across once.