# Plan: the CLI

Ordered, dependency-first tasks for `architecture/cli.md`, each mapped to the
gate(s)/test(s) it satisfies.

## Foundations

- [x] Add `clap_complete` + `clap_mangen` workspace deps; create the `cbd-cli`
  crate (clap defs default; `client` feature adds the gRPC executor).
- [x] `cbd-cli`: `Role`, `RemoteArgs`, `Connection`, the command enums, the
  three top-level `Cli`s, `generate_assets`, `print_completions`, and a
  `run_remote` stub. Compiles with and without `client`.

## Remote executor (`cbd-cli` `client` feature)

- [ ] Implement `run_remote`: dispatch every `LibraryCmd`/`QueueCmd`/`GlobalCmd`
  to its RPC via the generated client; pretty-print listings and the queue;
  concise messages for mutations. Add the missing `Stop` call. _(Gates: remote
  commands. Tests: a request-mapping unit test per group against a fake tonic
  server, or at least argument-parse tests for the clap tree.)_
- [ ] Map gRPC `Status`/transport errors to a short `color-eyre`/`eyre` report
  (no chain dump for "unreachable"). _(Gate: remote errors.)_

## Config writers

- [ ] Server: `ServerSettings::store(config_dir)` round-trips `[auth]`
  (preserve other roles, flat shape). _(Gate: guard config write. Test:
  set one role, reload, other roles intact.)_
- [ ] Client: a `Config` writer (load/modify/save `cbd-tui.toml`/`cbd.toml`).
  _(Gate: auth. Test: round-trip user/password/address.)_

## Server binary (`crabidy-server`)

- [ ] Replace the `Cli`/`HashPassword` with `cbd_cli::ServerCli`. No subcommand
  → `serve()` (unchanged). _(Gate: no-subcommand default.)_
- [ ] `guard`: hash (stdin fallback), print PHC, write config unless
  `--no-config`. Remove `hash-password`. _(Gate: guard.)_
- [ ] `scan`: walk + write tomls; `--capture`/`--move` via a new
  `CrabidyStore::ingest_file(path, move) -> StoreName` (factor the local-source
  half of the D4 capture flow). _(Gate: scan. Tests: toml written; capture
  dedups; move removes source; existing toml skipped.)_
- [ ] `library`/`queue`/`global` → `cbd_cli::run_remote` (enable `cbd-cli`
  `client`). `completions` → `print_completions`.

## Client binary (`cbd-tui`) and `cbd`

- [ ] Replace ClapSerde parsing: parse `cbd_cli::TuiCli`; load the TOML config
  and apply `remote`/`spectrum` overrides; no subcommand → `run(config)`.
  _(Gate: parsing/defaults. Tests: flag overrides file; first-run writes file.)_
- [ ] `auth` writes the client config; `library`/`queue`/`global` →
  `run_remote`; `completions` prints.
- [ ] `cbd`: parse `cbd_cli::CbdCli`; no subcommand → server + TUI (unchanged);
  subcommands dispatch to the server (guard/scan), client (auth), or remote
  (library/queue/global) paths. _(Gate: cbd union.)_

## Assets + build

- [ ] `build.rs` in each binary: build-dep `cbd-cli` (default features), call
  `generate_assets` for its `Command` into `OUT_DIR` and, when `CBD_ASSET_DIR`
  is set, into that dir. _(Gate: assets.)_
- [ ] devenv `gen-cli-assets` script: `CBD_ASSET_DIR=$PWD/dist cargo build`.
  _(Gate: assets.)_

## Docs + verification

- [ ] README: a CLI section (subcommands per binary, completions/man, the
  password-in-argv note); update the config section for `auth`/`guard`.
- [ ] `plan/summary.md`: what was built + deviations.
- [ ] `cargo test --workspace` green; clippy `-D warnings`, fmt, markdownlint
  clean (via `devenv shell`).