Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Coming from PowerShell
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

std/random

The std/random module has one command, random dice, which rolls dice. Import the module without a glob, so the command keeps its random prefix and sits next to the built-in random commands:

use std/random

With use std/random *, the command is just dice.

random dice

random dice returns a list with one random number per die. Each number is between 1 and the number of sides, inclusive. --dice sets how many dice to roll and defaults to 1, and --sides sets how many sides each die has and defaults to 6. Neither flag has a short form.

The result is always a list, even for one die, so use math sum to total a roll:

random dice --dice 3 --sides 20 | describe
# => list<int>
random dice --dice 2 | math sum

There must be at least one die, and a die must have at least two sides. Other values fail with the message of an assert greater check, whose labels point into the module's source:

random dice --sides 1
# => Error: nu::shell::error
# =>
# =>   × The amount of sides must be greater than 1
# =>   │ The condition *left > right* is not satisfied
# =>     ╭─[std/random/mod.nu:17:13]
# =>  16 │     greater $dice 0 "The amount of dice must be greater than 0"
# =>  17 │     greater $sides 1 "The amount of sides must be greater than 1"
# =>     ·             ───┬── ┬
# =>     ·                │   ╰── right: 1
# =>     ·                ╰── left: 1
# =>  18 │
# =>     ╰────

random dice --dice 0 fails the same way with The amount of dice must be greater than 0.

Edit this page on GitHub
Contributors: fdncred
Prev
std/math
Next
std/util