# randgen
[![CI][ci-badge]][ci-url]
[![Version][version-badge]][version-url]
![MSRV][msrv-badge]
![License][license-badge]
**randgen** is a tool which generates random bytes using a pseudorandom number
generator (PRNG).
## Installation
### From source
```sh
cargo install randgen
```
### From binaries
The [release page] contains pre-built binaries for Linux, macOS and Windows.
### How to build
Please see [BUILD.adoc].
## Usage
### Basic usage
Generate 1 KiB of random bytes:
```sh
randgen 1KiB
```
### Output formats
The following output formats are available:
- `raw` (encode the generated bytes as raw bytes)
- `base64` (encode the generated bytes as [base64])
- `hex` (encode the generated bytes as hex string)
The default output format is `raw`. To change this, use `-f` option.
```sh
randgen -f base64 256
```
### Supported PRNGs and CSPRNGs
Supported PRNGs are:
- [ISAAC] RNGs (if enabled at compile time)
- [Mersenne Twister] RNGs (if enabled at compile time)
- [PCG] RNGs (if enabled at compile time)
- [SFC] RNGs (if enabled at compile time)
- [Xorshift] family
- SplitMix64 RNG
- Xorshift RNG (if enabled at compile time)
- xoroshiro RNGs
- xoshiro RNGs
Supported CSPRNGs are:
- [ChaCha]-based RNGs
- [HC-128]-based RNG (if enabled at compile time)
The default RNG is `chacha12`. To change this, use `-r` option.
```sh
randgen -r pcg64 "2 MB"
```
### Providing a random seed
`-s` option allows you to specify a 64-bit unsigned integer random seed to be
used when creating a new PRNG. If this option is not specified, the RNG seeded
via random data from system sources such as the [`getrandom`] system call on
Linux.
```sh
$ randgen -f hex -r sfc32 -s 8 32B
24f48cd0c3f6a1c6e8d7b4dcff9578864aced749e4eb1805dfba8b6e21d0cba0
```
### Generate shell completion
`--generate-completion` option generates shell completions to standard output.
The following shells are supported:
- `bash`
- `elvish`
- `fish`
- `nushell`
- `powershell`
- `zsh`
Example:
```sh
randgen --generate-completion bash > randgen.bash
```
## Command-line options
Please see the following:
- [`randgen(1)`]
## Source code
The upstream repository is available at
<https://github.com/sorairolake/randgen.git>.
## Changelog
Please see [CHANGELOG.adoc].
## Contributing
Please see [CONTRIBUTING.adoc].
## License
Copyright (C) 2025 Shun Sakai (see [AUTHORS.adoc])
1. This program is distributed under the terms of either the _Apache License
2.0_ or the _MIT License_.
2. Some files are distributed under the terms of the _Creative Commons
Attribution 4.0 International Public License_.
This project is compliant with version 3.2 of the [_REUSE Specification_]. See
copyright notices of individual files for more details on copyright and
licensing information.
[ci-badge]: https://img.shields.io/github/actions/workflow/status/sorairolake/randgen/CI.yaml?branch=develop&style=for-the-badge&logo=github&label=CI
[ci-url]: https://github.com/sorairolake/randgen/actions?query=branch%3Adevelop+workflow%3ACI++
[version-badge]: https://img.shields.io/crates/v/randgen?style=for-the-badge&logo=rust
[version-url]: https://crates.io/crates/randgen
[msrv-badge]: https://img.shields.io/crates/msrv/randgen?style=for-the-badge&logo=rust
[license-badge]: https://img.shields.io/crates/l/randgen?style=for-the-badge
[release page]: https://github.com/sorairolake/randgen/releases
[BUILD.adoc]: BUILD.adoc
[base64]: https://en.wikipedia.org/wiki/Base64
[ISAAC]: https://www.burtleburtle.net/bob/rand/isaacafa.html
[Mersenne Twister]: https://www.math.sci.hiroshima-u.ac.jp/m-mat/MT/emt.html
[PCG]: https://www.pcg-random.org/
[SFC]: https://pracrand.sourceforge.net/RNG_engines.txt
[Xorshift]: https://cr.yp.to/chacha.html
[ChaCha]: https://prng.di.unimi.it/
[HC-128]: https://en.wikipedia.org/wiki/HC-128
[`getrandom`]: https://man7.org/linux/man-pages/man2/getrandom.2.html
[`randgen(1)`]: docs/man/man1/randgen.1.adoc
[CHANGELOG.adoc]: CHANGELOG.adoc
[CONTRIBUTING.adoc]: CONTRIBUTING.adoc
[AUTHORS.adoc]: AUTHORS.adoc
[_REUSE Specification_]: https://reuse.software/spec/