Metadata-Version: 2.5
Name: randompass
Version: 1.0.0
Summary: A simple generator of passwords and passphrases.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: click>=8.4.2
Requires-Dist: pyperclip>=1.11.0
Description-Content-Type: text/markdown

# randompass
## A simple generator of passwords and passphrases.

---
## Features

- Secure password generation using Python's `secrets` module.
- Guaranteed inclusion of selected character categories.
- Passphrase generation using a wordlist.
- Clipboard support.
- Save generated passwords/passphrases to a file.
- Generate multiple passwords/passphrases at once.
- CLI aliases: `pw` and `pp`.

---

## Installation
To install randompass, you need to have [uv](https://github.com/astral-sh/uv) installed.
### GitHub
```bash
git clone https://github.com/USERNAME/randompass.git
cd randompass
uv sync
```

Usage: `uv run randompass`

### PyPI
`uv tool install randompass`

Usage: `randompass`

## Usage

Choose a mode to generate passwords or passphrases.

```
$ randompass
Usage: randompass [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  passphrase
  password
  pw
  pp
```

For example, `randompass password` generates an 8-character password containing uppercase letters, digits, and special symbols.
All selected character categories are guaranteed to be included (with default settings).

And `randompass passphrase` generates a 5-word passphrase using the
default wordlist.

> **Note:** `password` and `pw` are aliases.
>
> **Note:** `passphrase` and `pp` are aliases.

### Arguments:
#### Password mode

| Argument | Description|
|---|---|
| `-h, --help` | Shows help page. |
| `-l, --length LENGTH` | Length of the password (default is 8). |
| `-u, --uppercase/--no-uppercase` | Whether uppercase letters should be included (enabled by default). |
| `-d, --digits/--no-digits` | Whether digits should be included (enabled by default). |
| `-s, --symbols/--no-symbols` | Whether special symbols should be included (enabled by default). |
| `-n, --count` | Number of passwords to generate (default is 1). |
| `-c, --copy` | Copy the password to the clipboard (disabled by default). |
| `-o, --output FILE` | Save the result to a file. |

---

#### Passphrase mode

| Argument | Description|
|---|---|
| `-h, --help` | Shows help page. |
| `-l, --length LENGTH` | Number of words in the passphrase (default is 5). |
| `-s, --separator` | Symbol that separates the words (default is "-"). |
| `-n, --count` | Number of passphrases to generate (default is 1). |
| `-c, --copy` | Copy the passphrase to the clipboard (disabled by default). |
| `-o, --output FILE` | Save the result to a file. |

> **Note:** Clipboard copying is unavailable if no supported clipboard
> mechanism is detected.
>
> Multiple results cannot be copied at once, and `--copy` cannot be
> combined with `--output`.

### Examples:
#### Password mode

Generate a 12-character password:

```
$ randompass password -l 12
/Sy"KG6dtv#G
```

Generate a 20-character password with no digits:

```
$ randompass password -l 20 --no-digits
bd,+?swxL.Y?d`{&'F:%
```

Generate 5 10-character passwords with no uppercase letters or special symbols:

```
$ randompass password -l 10 --no-uppercase --no-symbols -n 5
345ra5peus
cfppy97hkv
jy24huia4i
0cvjqfy871
70ygxqrh4d
```

Generate a password and copy it to the clipboard:

```
$ randompass password -c
4?[SOr9&
```

Generate 100 passwords with no digits and write them to `output.txt` (No console output):

```
$ randompass password --no-digits -n 100 -o output.txt
```


#### Passphrase mode

Generate a passphrase with 10 words:

```
$ randompass passphrase -l 10
shady-stretch-sulfate-snub-gummy-earthly-tipoff-icon-deflected-punctual
```

Generate a passphrase with 8 words and "_" separator:

```
$ randompass passphrase -l 8 -s _
corny_constrain_clunky_crispness_heaviness_strength_impending_saved
```

Generate a passphrase with 12 words, "=" separator and copy it to clipboard:

```
$ randompass passphrase -l 12 -s = -c
prelaw=oxidize=bonanza=uniquely=startling=happily=blurt=large=wok=corset=mustiness=arena
```

Generate 5 passphrases with "+" separator and write them to `example.txt` (No console output):

```
$ randompass passphrase -n 5 -s + -o example.txt
```

## Tests

Tests are located in [tests](tests/) folder.

Run them with pytest like:
```bash
uv run pytest
```

---

## Wordlist

The default wordlist is [EFF Large Wordlist](https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt).

## License
randompass distributes under [MIT License](LICENSE).