awesome-password

Because passwords don't need to suck.

Why Awesome Password?

Most password generators are either too random to remember or too predictable to trust.
Awesome Password gives you:

• ✨ Generates a list of 25 random password phrases to choose from — so you can pick one that resonates with you

• 🧠 Color-coded output in the terminal for different character types (no ambiguity!)

• 🔐 LOTS of entropy (using Node.JS crypto)

• 🎨 Customizable password formats

• 📜 Transparent explanation of strength: if you run with -v it will tell you all about it:

  Number of digits: 10
  Number of dividers: 24
  Number of bracket sets: 4
  Number of verbs: 11695
  Number of adjectives: 16797
  Number of nouns: 45965
  Number of adverbs: 3281
    
  Password form: 
  (00-Verb-Adjective-Noun-00)
    
  If the password in that form would be shorter than the minimum length of 30:
  (00-Verb-Adjective-Noun-Adverb-00)
  or
  (00-Verb-Adjective-Noun-Adverb-Adverb-00)
    
  Possible combinations (without adverbs):
  4 * 24 * 10 * 10 * 11695 * 16797 * 45965 * 10 * 10 = 8.7 billions of billions
    
  Possible combinations (with one adverb):
  4 * 24 * 10 * 10 * 11695 * 16797 * 45965 * 24 * 3281 * 10 * 10 = 682,571 billions of billions
    
  If a hacker can try 164 billion passwords per second, 
  and they know you use this pattern, it would take them
  up to a billion seconds to guess your password.
  That's up to 131,886 years.
  Even with a quantum computer using Grover's algorithm, it would (theoretically) take 363 years.
    
  If they don't know the pattern you are using for passwords, they will have to
  guess every single possible combination of letters, numbers, and special 
  characters until they figure out the right one. Since this program will never
  produce a password that is less than 30 characters in length:
    
  Number of unique possible characters in the password: 94
  Number of possible passwords with those characters: billions of billions of billions of billions of billions of billions
  That would take them billions of billions of billions years to guess.
  With quantum computers it would still take a billion years to guess.

Installation

npm i -g awesome-password

Alternatively, run it without installing it first:

npx awesome-password

Usage

$ awesome-password --help
Options:
      --help       Show help                                           [boolean]
      --version    Show version number                                 [boolean]
  -v, --verbose                                       [boolean] [default: false]
  -m, --minLength                                         [number] [default: 30]
  -d, --dividers                  [string] [default: "~`!@#$%^&*-_+=:;"',./?\|"]
  -b, --brackets                                  [string] [default: "[](){}<>"]
  -n, --digits                                  [string] [default: "0123456789"]
  -w, --words                                   [string] [default: "words.json"]
  -c, --choices                                           [number] [default: 10]
  -f, --form       the form of the password to generate (see Readme.md for
                   syntax and examples) [string] [default: "(00-v-a-n[-b]*-00)"]

🔤 Supported Form Syntax

The password form syntax defines a symbolic structure for generating randomized, human-readable passwords. Each character or block in the form corresponds to a specific token type. The parser translates this form into a sequence of generation steps.

📘 Syntax Overview

| Symbol | Meaning | Output Token | |---------------|----------------------------------|--------------------------| | ( | Opening bracket | 'bracket:start' | | ) | Closing bracket | 'bracket:end' | | 0 | Digit placeholder | 'digit' | | - | Divider character | 'divider' | | v | Verb | 'word:verb' | | a | Adjective | 'word:adjective' | | n | Noun | 'word:noun' | | b | Adverb | 'word:adverb' | | [ ... ]* | Repeat block (until long enough) | { repeat: [...] } |

🧪 Example

Form: (00-v-a-n[-b]*-00)

Parsed output:

[
  'bracket:start',
  'digit',
  'digit',
  'divider',
  'word:verb',
  'divider',
  'word:adjective',
  'divider',
  'word:noun',
  { repeat: ['divider', 'word:adverb'] },
  'divider',
  'digit',
  'digit',
  'bracket:end'
]

⚠️ Notes

• Repeat blocks ([...]) must be followed by * to indicate repetition.
• Nested repeat blocks and custom symbols are not supported.
• Invalid characters will throw a parsing error.

🧰 Custom Word Lists

You can supply your own word lists to generate passwords that reflect your domain, community, or personal vocabulary. This is especially useful for thematic passwords (e.g. sci-fi nouns, spiritual verbs, or brand-specific adjectives).

📦 Format

Your word list must be a JSON file with the following structure:

{
  "noun": ["tree", "river", "mountain"],
  "verb": ["run", "fly", "sing"],
  "adjective": ["bright", "gentle", "strong"],
  "adverb": ["quickly", "softly", "boldly"]
}

Each property should be an array of strings. You can include as many words as you like — the more variety, the more entropy.

🧪 Example Usage

awesome-password --words ./my-custom-words.json

This will only use words defined in your custom word list.