NameForge

Reproducible name wordlists and generators for character names and xkcdpass-style handles.

NameForge builds large realistic name datasets from public sources and provides tools to generate:

• Character names (First Last)
• xkcdpass-style handles
• Acrostic handles (e.g. npc, wizard)

The repository does not store generated datasets. Instead, it provides a clean pipeline to rebuild them from upstream sources.

---

Example Output

$ nameforge demo

== Names ==
Myia Mendlovic
Trenesha Eudy
Jaythen Muesse
Joules Lambing
Takala Glodek

== Handles (acrostic=npc) ==
Narducci-Pietruszynski-Capistrant
Negri-Parrigan-Coode
Nole-Puntiel-Credeur
Neureuther-Pangilinan-Claiborne
Nellenback-Pink-Capolongo

---

Installation

Clone the repository:

git clone https://github.com/routesmith/nameforge.git
cd nameforge

Install dependencies:

python -m pip install -r requirements.txt

Install the CLI locally (editable mode):

python -m pip install -e .

---

Quick Start

Build the datasets:

nameforge build

Run a demo:

nameforge demo

Generate names:

nameforge names -n 20 --unique

Generate handles:

nameforge handles --acrostic npc --seed 1337 --titlecase -n 10

---

CLI Usage

NameForge installs a CLI tool:

nameforge

Available commands:

nameforge build        Build wordlists
nameforge demo         Run demo output
nameforge names        Generate character names
nameforge handles      Generate handles

Show help:

nameforge --help

Show version:

nameforge --version

---

Generating Names

Examples:

nameforge names -n 20 --unique

Repeatable output:

nameforge names -n 20 --unique --seed 1337

Custom delimiter:

nameforge names -n 20 --delimiter "-"

Mix international names:

nameforge names -n 50 --p-us 0.85

---

Generating Handles (xkcdpass)

Basic handles:

nameforge handles -n 10

Acrostic example:

nameforge handles \
  --acrostic npc \
  --numwords 3 \
  --delimiter "-" \
  --seed 1337

Title-case output:

nameforge handles \
  --acrostic npc \
  --numwords 3 \
  --delimiter "-" \
  --seed 1337 \
  --titlecase

---

Makefile Commands

You can still use the Makefile directly.

Build datasets:

make

Run demo:

make demo

Verify outputs:

make check

Remove generated data:

make clean

Remove downloaded archives:

make clean-zips

Remove cloned source datasets:

make clean-sources

---

Project Structure

nameforge
├── Makefile
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── scripts/
│   ├── build_lists.sh
│   ├── gen_names.py
│   └── gen_handles.py
├── src/
│   └── nameforge/
│       ├── __init__.py
│       └── cli.py
└── data/
    ├── raw/        # downloaded source datasets (ignored)
    └── derived/    # generated wordlists (ignored)

---

Data Sources

NameForge builds its wordlists from external datasets:

• US Social Security Administration baby names
• US Census 2010 surname list
• https://github.com/sigpwned/popular-names-by-country-dataset

These datasets are not redistributed by this repository. They are downloaded during the build process and remain subject to their respective licenses.

Derived datasets are generated locally via make or nameforge build.

---

Dependencies

NameForge builds on several excellent open source projects:

• https://github.com/redacted/XKCD-password-generator (xkcdpass)
• https://github.com/sigpwned/popular-names-by-country-dataset

---

Notes

Wordlists are filtered to:

• ASCII Latin letters
• Optional -
• Optional '

Handles internally lowercase the wordlist to ensure reliable acrostic matching. Output formatting can optionally be restored with --titlecase.

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.