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

cargo install rdice-cli

Usage

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:

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:

~/.config/rdice/config.toml

Example:

[[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.