A command-line dice roller for tabletop RPGs. Supports standard dice notation, advantage/disadvantage, keep-highest/lowest, exact probability computation, and named presets.
roll <expression> [options]
roll --tui [expression]
roll --repl
roll --save <name> <expression>
roll --list
roll --delete <name>
| Expression | Meaning |
|---|---|
2d10+4 |
Roll 2d10, add 4 |
d20 |
Roll a single d20 |
adv d20+5 |
Roll d20 with advantage (take higher), add 5 |
dis d20-1 |
Roll d20 with disadvantage (take lower), subtract 1 |
2d6+1d4+3 |
Multiple dice groups with a flat bonus |
4d6kh3 |
Roll 4d6, keep the highest 3 (D&D ability scores) |
4d6kl1 |
Roll 4d6, keep the lowest 1 |
Use -n / --times to roll the same expression several times at once:
roll 2d6+3 -n 5
# #1: 2d6+3 => [4, 2] (+3) = 9
# #2: 2d6+3 => [6, 1] (+3) = 10
# ...
Use --stats to print the theoretical min, max, and mean alongside any output:
roll 2d6+3 --stats
# 2d6+3 => [5, 3] (+3) = 11
# [min=5, max=15, mean=10.00]
Use --prob to calculate the chance of rolling at least a given value.
For simple expressions (no advantage/disadvantage, no keep), the result is
computed exactly via polynomial convolution; otherwise it falls back to
Monte Carlo simulation:
roll d20 --prob 15
# P(1d20 >= 15) = 30.0000% (exact)
roll adv d20 --prob 15
# P(adv 1d20 >= 15) = 50.97% (509700 / 1000000 sims)
The number of simulations defaults to 1,000,000 and can be changed with the SIMS
environment variable (e.g. SIMS=500000 roll d20 --prob 15).
Use --dist to see the full probability distribution as an ASCII histogram.
Cannot be combined with --prob.
roll 2d6 --dist
# Distribution for 2d6 (1000000 simulations):
# 2 | 2.8% ███
# 3 | 5.5% ██████
# ...
The simulation count defaults to 1,000,000 and can be changed with the SIMS
environment variable.
Use --repl to drop into an interactive session where you can type expressions
one per line without re-invoking the binary:
roll --repl
# Roll REPL — type a dice expression or 'quit' to exit.
# > adv d20+5
# adv 1d20+5 => [18] vs [7] (+5) = 23
# > 4d6kh3
# 4d6kh3 => [6, 5, 3] = 14
# > quit
Save frequently-used expressions as named presets stored in
~/.config/roll/presets.toml:
roll --save attack "adv d20+7"
# Saved preset 'attack' = 'adv d20+7'.
roll --list
# Saved presets:
# attack = adv d20+7
roll attack
# adv 1d20+7 => [17] vs [9] (+7) = 24
roll --delete attack
# Deleted preset 'attack'.
Preset names are resolved case-insensitively before the input is parsed as a
dice expression. Any roll option (--times, --stats, --prob, --dist)
works normally with presets.
Use --tui / -t to launch a full-screen terminal interface:
roll --tui
roll adv d20+5 --tui # opens TUI with expression pre-filled
The TUI has three screens:
- Roller — type a dice expression and press Enter to roll. Results show individual dice with natural-max/natural-min highlighting, plus an auto-generated distribution chart. A presets sidebar (Tab) lets you browse and roll saved presets.
- History — scrollable log of all rolls from the current session (F2).
- Help — key binding reference overlay (F1).
| Key | Action |
|---|---|
Enter |
Roll the current expression |
Tab |
Toggle presets sidebar |
F1 |
Toggle help overlay |
F2 |
Open history screen |
Up / Down |
Navigate input history (Roller) |
Left / Right |
Move cursor within input |
j / k |
Navigate presets list (when sidebar focused) |
d |
Delete selected preset (press twice to confirm) |
[ / ] |
Move distribution target left / right |
PageUp / PageDown |
Scroll history (History screen) |
Ctrl+A / Ctrl+E |
Move cursor to start / end of input |
Ctrl+U |
Clear input line |
Esc |
Dismiss error, close sidebar/overlay, or quit |
Ctrl+C |
Quit immediately |
cargo build --release
With Rust installed, get the package from crates.io:
cargo install rollcli
Prebuilt Linux, macOS, and Windows archives are available from the
GitHub Releases page. Verify the
download against the accompanying SHA256SUMS.txt, then place the roll
binary on your PATH.
MIT