crabidy/docs/src/clients/cbd.md

The cbd bundle

cbd is the server and the terminal client in one process, for the single-machine case where you just want to play music without running a separate server. Starting cbd starts an in-process server and then runs the terminal UI against it; everything else — the config format, the gRPC wire, every feature — is exactly the same as running the two halves separately.

What it does at start

direction: right

cbd: "cbd (one process)" {
  boot: "main: spawn server,\nwait, run TUI"
  srv: "in-process server\n(0.0.0.0:50051)"
  tui: "cbd-tui"
  boot -> srv: "spawn (port taken → adopt)"
  boot -> tui: after readiness
  tui -> srv: localhost gRPC
}

1. It spawns the server on a background task. If the port is already taken because a standalone crabidy-server is already running, cbd logs that and carries on — the TUI simply connects to the existing server instead of failing.
2. It waits until the configured server address accepts a connection (bounded retries, then a clear error), so the TUI never starts against a server that is not ready yet.
3. It runs the TUI exactly as cbd-tui would.

The bundled TUI talks to the in-process server over localhost gRPC, the same way a remote TUI would — there is no in-process shortcut. Quitting the TUI ends the process, and with it the in-process server; the queue is persisted continuously (see Queue and playback), so the next start restores it.

Its own config

cbd reads its own cbd.toml, not cbd-tui.toml. The two files have the same options but are separate so the self-contained cbd (defaulting to its localhost server) and a cbd-tui pointed at a remote server can coexist on one machine without one dragging the other's address. See Configuration.

cbd also carries the CLI subcommands of both halves — the server's guard/scan, the client's auth, and the shared library/queue/global remote commands. See Command line.