# > generate-pw
### Randomly generate, strengthen, and validate cryptographically-secure passwords.
## 💡 About
**generate-pw** is a lightweight, easy-to-use library that allows you to randomly generate, strengthen & validate cryptographically-secure password(s).
- **No external dependencies —** Only built-in crypto methods used for secure randomization
- **Highly customizable —** Specify length, quantity, charsets to use, etc.
- **Multi-environment support —** Use in Node.js or the web browser
- **Command line usable —** Just type `generate-pw`, that's it
## ⚡ Installation
As a **global utility**:
```
$ npm install -g generate-pw
```
As a **runtime dependency**, from your project root:
```
$ npm install generate-pw
```
## 🔌 Importing the API
#### 
ES Modules (ESM):
```js
import pw from 'generate-pw'
```
#### 
CommonJS (CJS):
```js
const pw = require('generate-pw')
```
#### [
][web-usage][
][web-usage][
][web-usage][
][web-usage][
][web-usage] Web:
[web-usage]: #-web
```html
```
#### [
][greasemonkey-usage][
][greasemonkey-usage][
][greasemonkey-usage][
][greasemonkey-usage][
][greasemonkey-usage][
][greasemonkey-usage] Greasemonkey:
[greasemonkey-usage]: #-greasemonkey-1
```js
...
// @require https://cdn.jsdelivr.net/npm/generate-pw@2/dist/generate-pw.min.js
// ==/UserScript==
...
```
## 📋 API usage
### `generatePassword([options])`
Generates **one** password if `qty` option is not given, returning a string:
```js
const password = pw.generatePassword({ length: 11, numbers: true })
console.log(password) // sample output: 'bAsZm3mq6Qn'
```
...or **multiple** passwords if `qty` option is given, returning an array of strings:
```js
const passwords = pw.generatePassword({ qty: 5, length: 8, symbols: true })
console.log(passwords)
/* sample output:
generatePassword() » Generating passwords...
generatePassword() » Passwords generated!
generatePassword() » Check returned array.
[ '!zSf@Q.s', '!,HT\\;m=', '?Lq&FV>^', 'gf}Y;}Ne', 'Stsx(GqE' ]
*/
```
**💡 Note:** If no options are passed, passwords will be 8-chars long, consisting of upper/lower cased letters.
See: [Available options](#available-options-for-generate-functions)
#
### `generatePasswords(qty[, options])`
Generates **multiple** passwords based on `qty` given, returning an array of strings:
```js
const passwords = pw.generatePasswords(5, { length: 3, uppercase: false })
console.log(passwords)
/* sample output:
generatePasswords() » Generating passwords...
generatePasswords() » Passwords generated!
generatePasswords() » Check returned array.
[ 'yilppxru', 'ckvkyjfp', 'zolcpyfb' ]
*/
```
**💡 Note:** If no `qty` arg is passed, just one password will be generated, returned as a string.
See: [Available options](#available-options-for-generate-functions)
#
### `strictify(password[, requiredCharTypes, options])`
Modifies `password` given to use at least one character of each `requiredCharTypes` element passed, returning a string:
```js
const strictPW = pw.strictify('abcdef', ['numbers', 'symbols'])
console.log(strictPW) // sample output: 'a!c2ef'
```
**💡 Note:** If no `requiredCharTypes` array is passed, all available types will be required.
Available `requiredCharTypes` are: `['numbers', 'symbols', 'lower', 'upper']`
Available options (passed as object properties):
Name | Type | Description | Default Value
----------|---------|-----------------------------------|---------------
`verbose` | Boolean | Show logging in console/terminal. | `true`
#
### `validateStrength(password[, options])`
Validates the strength of a password, returning an object containing:
- `strengthScore` (0–100)
- `recommendations` array
- `isGood` boolean (`true` if `strengthScore` >= 80)
Example:
```js
const pwStrength = pw.validateStrength('Aa?idsE')
console.log(pwStrength)
/* outputs:
validateStrength() » Validating password strength...
validateStrength() » Password strength validated!
validateStrength() » Check returned object for score/recommendations.
{
strengthScore: 60,
recommendations: [
'Make it at least 8 characters long.',
'Include at least one number.'
],
isGood: false
}
*/
```
Available options (passed as object properties):
Name | Type | Description | Default Value
----------|---------|-----------------------------------|---------------
`verbose` | Boolean | Show logging in console/terminal. | `true`
#
### Available options for `generate*()` functions
Any of these can be passed into the options object for each `generate*()` function:
Name | Type | Description | Default Value
----------------------|---------|--------------------------------------------------------------------------------|---------------
`verbose` | Boolean | Show logging in console/terminal. | `true`
`length` | Integer | Length of password(s). | `8`
`qty` | Integer | Number of passwords to generate. | `1`
`strength` | String | `<'weak'\|'basic'\|'strong'>` Apply strength preset. | `''`
`charset` | String | Characters to include in password(s). | `''`
`exclude` | String | Characters to exclude from password(s). | `''`
`numbers` | Boolean | Allow numbers in password(s). | `false`
`symbols` | Boolean | Allow symbols in password(s). | `false`
`lowercase` | Boolean | Allow lowercase letters in password(s). | `true`
`uppercase` | Boolean | Allow uppercase letters in password(s). | `true`
`similarChars` | Boolean | Include similar characters (e.g. o,0,O,i,l,1,\|) in password(s). | `false`
`strict` | Boolean | Require at least one character from each allowed character set in password(s). | `true`
`entropy` | Boolean | Calculate/log estimated entropy. | `true`
##### _*Only available in [`generatePassword([options])`](#generatepasswordoptions) since [`generatePasswords(qty[, options])`](#generatepasswordsqty-options) takes a `qty` argument_
## 💻 Command line usage
**generate-pw** can also be used directly from the command line. The basic command is:
```
$ generate-pw
```
#
### Command line options
```
Parameter options:
--length=n Generate password(s) of n length.
--qty=n Generate n password(s).
--charset=chars Only include chars in password(s).
--exclude=chars Exclude chars from password(s).
--ui-lang="code" ISO 639-1 code of language to display UI in.
--config="path/to/file" Load custom config file.
Boolean options:
-w, --weak Generate weak password(s).
-b, --basic Generate basic strength password(s).
-t, --strong Generate strong password(s).
-N, --no-numbers Disallow numbers in password(s).
-Y, --no-symbols Disallow symbols in password(s).
-L, --no-lowercase Disallow lowercase letters in password(s).
-U, --no-uppercase Disallow uppercase letters in password(s).
-S, --similar-chars Include similar characters in password(s).
-S, --unstrict Don't require at least one character from
each allowed character set in password(s).
-E, --no-entropy Don't calculate/log estimated entropy.
-q, --quiet Suppress all logging except errors.
Commands:
-i, --init Create config file (in project root).
-h, --help Display help screen.
-v, --version Show version number.
--stats Show npm stats.
--debug [targetKey] Show debug logs.
```
#
### Configuration file
**generate-pw** can be customized using a `generate-pw.config.mjs` or `generate-pw.config.js` placed in your project root.
Example defaults:
```js
export default {
length: 12, // length of passwords to generate
qty: 1, // # of passwords to generate
strength: '', // <'weak'|'basic'|'strong'> apply strength preset
charset: '', // only include chars in password(s)
exclude: '', // exclude chars from password(s)
excludeNums: false, // disallow numbers in password(s)
excludeSymbols: false, // disallow symbols in password(s)
excludeLowerChars: false, // disallow lowercase letters in password(s)
excludeUpperChars: false, // disallow uppercase letters in password(s)
similarChars: false, // include similar chars in password(s)
unstrict: false, // don't require 1+ char from each allowed charset in password(s)
noEntropy: false, // don't calculate/log estimated entropy
quietMode: false // suppress all logging except errors
}
```
💡 Run `generate-pw init` to generate a template `generate-pw.config.mjs` in your project root.
## 🏛️ MIT License
**Copyright © 2024–2026 [Adam Lui](https://github.com/adamlui) & contributors.**
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## 🛠️ Related utilities
### 
[generate-ip](https://github.com/adamlui/js-utils/tree/main/generate-ip/#readme) 
> Randomly generate, format, and validate IPv4 + IPv6 + MAC addresses.
[Install](https://github.com/adamlui/js-utils/tree/main/generate-ip/docs/#-installation) /
[Readme](https://github.com/adamlui/js-utils/tree/main/generate-ip/docs/#readme) /
[API usage](https://github.com/adamlui/js-utils/tree/main/generate-ip/docs/#-api-usage) /
[CLI usage](https://github.com/adamlui/js-utils/tree/main/generate-ip/docs/#-command-line-usage) /
[Discuss](https://github.com/adamlui/js-utils/discussions)
### 
[geolocate](https://github.com/adamlui/js-utils/tree/main/geolocate/#readme)
> Fetch IP geolocation data from the CLI.
[Install](https://github.com/adamlui/js-utils/tree/main/geolocate/docs/#-installation) /
[Readme](https://github.com/adamlui/js-utils/tree/main/geolocate/docs/#readme) /
[CLI usage](https://github.com/adamlui/js-utils/tree/main/geolocate/docs/#-command-line-usage) /
[API usage](https://github.com/adamlui/js-utils/tree/main/geolocate/docs/#-api-usage) /
[Discuss](https://github.com/adamlui/js-utils/discussions)
[
][js-utils]
[**More JavaScript utilities**][js-utils] /
Discuss /
Report bug /
Report vulnerability /
Back to top ↑
[js-utils]: https://github.com/adamlui/js-utils/#readme
