# rdice-cli
`rdice-cli` provides the `rdice` command-line dice roller. It uses
`rdice-core` for dice definitions, expression parsing, rolling, and
deterministic analysis.
## Install
```sh
cargo install rdice-cli
```
## Usage
```sh
rdice roll [-f|--folded] [-x|--expanded] [-E|--ev] [-R|--range] <dice-expr...>
rdice <analysis-option...> <dice-expr...>
rdice list
rdice config path
rdice config edit
rdice config check
rdice help [roll|list|config]
rdice --version
```
Examples:
```sh
rdice roll 5d6
rdice roll -x 4d6
rdice roll -f -E -R 3d13 2coin 5 -3
rdice -E -R 3d6 5 -3
```
The top-level form performs analysis without rolling and requires at least one
of `-E`/`--ev` or `-R`/`--range`. Use the explicit `roll` command to roll dice.
`--folded` and `--expanded` are mutually exclusive.
Both rolling and analysis require at least one die; modifiers cannot be used as
a modifier-only calculator. A token such as `3d13` means three dynamic numeric
13-sided dice, while `2coin` means two rolls of the configured `coin` die.
CLI output uses ANSI colors on terminals. Piped or redirected output disables
colors automatically. Pass `--no-color` or set `NO_COLOR` to disable color
output explicitly.
## Custom Dice
The CLI reads custom dice from `RDICE_CONFIG_PATH` when set. Otherwise it uses:
```text
~/.config/rdice/config.toml
```
Example:
```toml
[[dice]]
name = "coin"
faces = ["heads", "tails"]
[[dice]]
name = "fate"
faces = [-1, 0, 1]
```
Custom dice use their configured names directly, so `2coin` resolves to the
configured `coin` die.
Because the CLI expression adapter reserves integers as modifiers, leading
digits as roll counts, and leading `-` tokens as options, configured die names
must not be empty, contain whitespace, be integers, or begin with an ASCII
digit or `-`. Names must also remain unique under ASCII case-insensitive
matching and must not collide with built-in or dynamic numeric die names.
These are CLI-only syntax constraints; `rdice-core` does not impose them.
The CLI config is a declarative definition source, not a persisted engine
state: local core IDs are assigned in file order each time the process starts.
For compatibility, a legacy `✽` prefix in a configured name is accepted and
removed by the CLI adapter. The file is not rewritten automatically.
Use `rdice config check` after editing to validate the file without rolling. If
the optional file is missing, the command reports that only built-in dice are
active. Unknown TOML fields are rejected so misspelled keys cannot be silently
ignored. If set, `RDICE_CONFIG_PATH` must be non-empty.
## License
Licensed under the MIT License.