termname

Algorithmic, local-first terminal username generator.

termname is a fast, highly configurable username generation engine designed for developers and terminal users. It creates personalized username candidates using deterministic algorithms, controlled randomness, curated word dictionaries, name mutations, combinations, and a multi-factor candidate scoring system.

No AI, no LLMs, zero telemetry, and 100% offline. Everything runs algorithmically on your machine.

Features

• No AI / Networks: Generates hundreds of candidates instantly using local algorithms.
• Highly Configurable: Use specific themes, restrict lengths, lengths, enforce numeric/separator inclusion, etc.
• Seeded generation: Reproduce exact identical variations using a seed value, perfect for scripting or testing.
• Rich Strategy Engine: Uses 10+ candidate generation strategies (name mutations, prefixes, initial combos, technical variants, etc.).
• Style System: Multiple built-in styles (minimal, developer, aesthetic, unix, gaming, etc.).
• CLI & API: Use interactively, from shell scripts, or programmatically via the Node.js API.

Installation

Install globally using npm to use the CLI from anywhere:

npm install -g termname

To use it as a library in your Node.js project:

npm install termname

CLI Usage

Interactive Mode

Simply run the command with no arguments:

termname

The CLI will prompt you for your name, style preferences, and candidate counts, then present numbered suggestions.

Non-Interactive Options

termname --name Sagnik

termname --name Sagnik --style minimal

termname --random --count 20

termname --name Sagnik --min-length 5 --max-length 12

termname --name Sagnik --seed 12345 --json

Options:

• -n, --name - Name or display name.
• -s, --style - Username style (minimal, developer, aesthetic, gaming, retro, dark, professional, unix, random).
• -c, --count - Number of suggestions to generate (default: 10).
• --min-length, --max-length - Enforce length limits.
• --allow-numbers, --allow-separators - Explicitly allow or disallow character patterns.
• --separator - Specific separator character (e.g. _ or -).
• -w, --words - Path to a custom word list text file (one word per line).
• --seed - Ensures deterministic reproducible generation.
• -r, --random - Generate random usernames without requiring a name.
• -j, --json - Output raw JSON results.

Programmatic API Usage

The package exposes a clean API for TypeScript/JavaScript projects:

import { generateUsernames, generateUsernameStrings } from "termname";

// Detailed options
const suggestions = generateUsernames({
    name: "Sagnik",
    style: "minimal",
    count: 10
});

console.log(suggestions);
/**
 * [
 *   { username: 'sagnix', score: 100, strategy: 'name_phonetic_x', explanation: '...' },
 *   { username: 'sagvoid', score: 98, ... }
 * ]
 */

// Simple string array output
const strings = generateUsernameStrings({ name: "Alex" });
console.log(strings); // ['alex', 'alexe', ...]

How It Works

1. Features & Tokens: Parses spaces, normalizes cases, breaks multi-word names into tokens, extracts initials.
2. Strategy Engine: Matches words to category dictionaries (e.g. linux → unix, shell, kernel). It spawns an initial pool of hundreds of candidates using different techniques.
3. Scorer: Applies multi-factor evaluation scoring candidates based on name retention, pronounceability, sweet-spot lengths, theme relevance, checking constraints.
4. Ranking: Extracts top recommendations assuring Strategy Diversity so the final list contains distinct variation shapes rather than duplicate suffixes.

Configuration File

You can create a termname.config.json in your project folder to define defaults:

{
  "defaultStyle": "unix",
  "defaultCount": 5,
  "allowNumbers": false,
  "minLength": 4,
  "maxLength": 15
}

CLI arguments explicitly override matching options mapped from configuration defaults.

License

MIT