# Command line

<!-- toc -->

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](./tui.md), and `cbd` runs the
[in-process server + TUI](./cbd.md).

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](../config.md) 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](../auth.md)); leave empty against an open server.

```sh
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](../library.md)
  (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](../store.md)) mutate it.
- `queue insert <POS> <PATH>…` inserts **at** `POS`, pushing the row that
  was there down; `0` puts tracks at the front.
- `queue show` prints the [queue](../queue.md); `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](../auth.md)). With the password omitted it reads stdin.

```sh
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`](../providers/fs.md). 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](../store.md).

```sh
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](../config.md#the-audio-output-device).

```sh
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](../build-features.md).

```console
$ 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](../config.md), so
you do not have to edit the file by hand.

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

```admonish warning
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

```sh
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`.