# RANDSUM CLI — Command-Line Dice Roller

The **RANDSUM CLI** is a command-line dice roller powered by `@randsum/roller`. Pass any RANDSUM notation and get instant results in your terminal.

## Installation

Install globally with Bun or npm:

<CodeExample lang="bash" code={`# Bun
bun add -g @randsum/cli

# npm
npm install -g @randsum/cli

# Run without installing
npx @randsum/cli 4d6L`} />

Requires Node >= 18 or Bun.

## Usage

```
randsum [notation...] [flags]
```

Pass one or more notation arguments. Multiple notations are combined into a single roll result.

<CodeExample lang="bash" code={`randsum 4d6L             # Roll 4d6, drop lowest
randsum 2d20L +5         # Roll with advantage + modifier
randsum 1d20 -v          # Verbose output
randsum 3d6 --json       # JSON output
randsum 4d6L -r 6        # Roll 6 times`} />

## Flags

| Flag | Description |
|---|---|
| `-v`, `--verbose` | Show detailed roll breakdown (raw dice, kept dice, total) |
| `--json` | Output result as JSON. With `-r`, emits JSON-lines (one object per line) |
| `-t`, `--total` | Print only the numeric total, one per line (for scripting). Cannot combine with `--json` |
| `-r N`, `--repeat N` | Roll N times and print each result |
| `-s N`, `--seed N` | Use a seeded random number generator for reproducible results |
| `-h`, `--help` | Show help text |
| `-V`, `--version` | Show installed version |

## Output Formats

### Compact (default)

Shows the total, followed by the final dice values in brackets, followed by any modifier descriptions.

```
14  [3, 5, 6]  drop lowest 1
```

### Verbose (`-v`)

Multi-line breakdown showing each roll group with raw dice, kept dice (when modifiers apply), and total.

```
Roll:  4d6, drop lowest 1
Raw:   [2, 3, 5, 6]
Kept:  [3, 5, 6]
Total: 14
```

### JSON (`--json`)

Structured JSON output. Useful for piping into other tools.

```json
{
  "total": 14,
  "rolls": [
    {
      "description": ["4d6", "drop lowest 1"],
      "raw": [2, 3, 5, 6],
      "kept": [3, 5, 6],
      "total": 14
    }
  ]
}
```

When combined with `-r N`, `--json` emits **JSON-lines** — one JSON object per
line rather than a single array — so you can stream each roll into `jq`:

<CodeExample lang="bash" code={`randsum 4d6L --json -r 6 | jq '.total'`} />

### Total (`-t`)

Prints only the numeric total, one per line. Ideal for scripting — no brackets,
labels, or JSON to parse. Composes with `-r` (one total per line) but cannot be
combined with `--json`.

```
14
```

## Examples

<CodeExample lang="bash" code={`# D&D ability score generation — roll 6 sets of 4d6 drop lowest
randsum 4d6L -r 6

# Advantage roll — two d20s, drop the lowest (keep highest)
randsum 2d20L

# Disadvantage roll — two d20s, drop the highest (keep lowest)
randsum 2d20H

# Seeded roll for reproducible results
randsum 2d6 -s 42

# Combine multiple notation groups
randsum 2d6+3 1d8

# JSON output for scripting
randsum 4d6L --json | jq '.total'

# JSON-lines: one object per repeat, streamed into jq
randsum 4d6L --json -r 6 | jq '.total'

# Total-only output for shell scripts
randsum 4d6L -t -r 6`} />

## Links

- [Source code](https://github.com/RANDSUM/randsum/tree/main/apps/cli)
- [RANDSUM notation reference](https://randsum.dev/notation/randsum-dice-notation/)
- [\`@randsum/roller\` API reference](https://randsum.dev/roller/api-reference/)