crabidy/docs/src/clients/cli.md

Command line

Every binary is a clap CLI. Run any of them with --help (and any subcommand with --help) for the full surface. Running a binary with no subcommand behaves as it always has: crabidy-server runs the server, cbd-tui runs the TUI, and cbd runs the in-process server + TUI.

The subcommands fall into three groups: the shared remote commands (available on every binary), the server-only commands, and the client-only command.

Remote commands: library / queue / global

library, queue, and global are available on all three binaries and act as a scriptable remote control: each one connects to a running server over gRPC, sends a single command, prints the result, and exits. A crabidy-server running these is just acting as a client to whatever server is up — including its own.

Connection flags go before the subcommand and fall back to the client config file (cbd-tui.toml / cbd.toml) when omitted:

• --address <URL> — the server to connect to.
• --user <role> / --password <pw> — basic-auth credentials, using the role name as the user (see Roles and authorization); leave empty against an open server.

crabidy-server library list /tidal        # browse a node
cbd-tui --address http://pi:50051 queue append /fs/album
cbd global play                           # toggle play/pause
cbd global volume -- -0.1                 # lower the volume

• library list [PATH] browses a library node (default /), printing its child nodes and tracks; captured rows are marked. library create/rename/delete, and library save/ capture (the w/W equivalents into /crabidy — see The crabidy store) mutate it.
• queue show prints the queue; queue append/insert/ replace <PATH>…, queue remove <POS>…, queue clear [--keep-current], queue set-current <POS>, queue save/capture <NAME>, queue shuffle, and queue repeat change it.
• global play/stop/next/prev/restart/mute and global volume <DELTA> control playback.

Server commands

These live on crabidy-server (and cbd). They act on the server's own config and content store, not over the wire.

guard <role> [password] [--no-config] hashes a role password with argon2id and prints the PHC string to stdout. Unless --no-config is given, it also writes the hash into the role's field in crabidy-server.toml's [auth], preserving the other roles. Roles are owner, queue-owner, and queue-appender (see Roles and authorization). With the password omitted it reads stdin.

printf '%s' 'my-password' | crabidy-server guard owner
crabidy-server guard queue-owner 'pw' --no-config   # just print the PHC

scan <path> [--capture|--move] walks a folder recursively and drops a .cbd-track.toml beside every audio file, so the folder browses as a tree under /fs. Existing .cbd-track.toml files are left untouched. By default the sidecar points at the audio in place. --capture copies each file into the content store instead (the sidecar points there, de-duplicated); --move moves it into the store, leaving only the sidecar behind. See The crabidy store.

crabidy-server scan ~/Music                # index in place
crabidy-server scan ~/Downloads --capture  # copy audio into the store

audio-devices [device] lists the audio output devices the server can see, marking the one the current config selects. Given a name (or a fragment of one) it writes [audio] device into crabidy-server.toml and then lists, so one command both configures and confirms — see The audio output device.

crabidy-server audio-devices               # list
crabidy-server audio-devices Headphones    # pin one, then list

features prints the build features this binary was compiled with — the providers it can mount, then the extras (opus, spectrum, web-ui) — one per line. It answers "why is /tidal missing?" without guesswork; see Tailored builds.

$ crabidy-server features
fs
crabidy
orphans
opus

Client command: auth

auth <role> [password] [--address ADDR] lives on cbd-tui (and cbd). It writes the role name as the user, the cleartext password, and optionally the address into the client config, so you do not have to edit the file by hand.

cbd-tui auth owner 'my-password'
cbd-tui auth queue-owner 'pw' --address http://pi:50051

A password given as a command-line **argument** is visible in the
process list (e.g. `ps`) for as long as the command runs. Prefer
omitting it: `guard` then reads the password from stdin, which keeps it
out of argv and is pipe-friendly. The client config written by `auth`
stores the password in plaintext, so keep that file private.

Completions and man pages

cbd-tui completions bash                 # print a completion script
devenv shell -- gen-cli-assets           # write dist/completions + dist/man

Each binary can print a shell completion script (bash/zsh/fish) to stdout with the hidden completions <shell> subcommand. gen-cli-assets builds the binaries with CBD_ASSET_DIR=$PWD/dist, producing dist/completions/** and dist/man/*.1 for all three binaries. Every ordinary build also emits these into the crate's OUT_DIR.