roll
A command-line dice roller for tabletop RPGs. Supports standard dice notation, advantage/disadvantage, keep-highest/lowest, exact probability computation, and named presets.
Usage
roll <expression> [options]
roll --repl
roll --save <name> <expression>
roll --list
roll --delete <name>
Dice expressions
| 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 |
Rolling multiple times
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
# ...
Theoretical statistics
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]
Probability estimation
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 --sims.
Distribution histogram
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% ██████
# ...
Interactive REPL
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
Named presets
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.
Building
cargo build --release
License
MIT