==========
xkcdpass
==========

------------------------------------------------
generate memorable, secure multiword passphrases
------------------------------------------------

:Author: |author|
:Date: 2022-02-23
:Copyright: |license|.
:Manual section: 1
:Manual group: Admin

..  |command| replace:: **xkcdpass**
..  |license| replace::
        BSD license, attribution and disclaimer required, no endorsement allowed


SYNOPSIS
========

| |command| [ `option` ... ]
| |command| **--help**


DESCRIPTION
===========

A flexible and scriptable password generator which generates strong
passphrases, inspired by XKCD 936::

    $ xkcdpass
    > correct horse battery staple


OPTIONS
=======

**--help**

    Describe how to use this command.

**--wordfile** `WORDFILE`, **-w** `WORDFILE`

    Specify that the file `WORDFILE` contains the list of valid words
    from which to generate passphrases.

**--min** `MIN_LENGTH`

    Generate passphrases containing at least `MIN_LENGTH` words. (Default: 5)

**--max** `MAX_LENGTH`

    Generate passphrases containing at most `MAX_LENGTH` words. (Default: 9)

**--numwords** `NUM_WORDS`, **-n** `NUM_WORDS`

    Generate passphrases containing exactly `NUM_WORDS` words. (Default: 6)

**--interactive**, **-i**

    Generate and output a passphrase, query the user to accept it, and
    loop until one is accepted.

**--valid-chars** `VALID_CHARS`, **-v** `VALID_CHARS`

    Limit passphrases to only include words matching the regex pattern
    `VALID_CHARS` (e.g. ``'[a-z]'``).

**--verbose**, **-V**

    Report various metrics for given options.

**--acrostic** `ACROSTIC`, **-a** `ACROSTIC`

    Generate passphrases with an acrostic matching `ACROSTIC`.

**--count** `COUNT`, **-c** `COUNT`

    Generate `COUNT` passphrases. (Default: 1)

**--delimiter** `DELIM`, **-d** `DELIM`

    Separate words within a passphrase with `DELIM`. (Default: ' ')

**--separator** `SEP`, **-s** `SEP`

    Separate multiple passphrases with `SEP`. (Default: U+000A LINE
    FEED)

**--case** `CASE`, **-C** `CASE`

    Set the case of each word in the passphrase by method `CASE`.
    (Default: ``lower``)

    Valid `CASE` values are ``alternating``, ``upper``, ``lower``,
    ``first``, ``random``.


EXAMPLES
========

* | |command|

  Generates one passphrase with the default options. Example output::

      pinball previous deprive militancy bereaved numeric

* | |command| --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid_chars='[a-z]'

  Generates 5 passphrases, all from lower-case words and meeting the
  acrostic “chaos”, delimited by the “|” character. Example output::

      collar|highly|asset|ovoid|sultan
      caper|hangup|addle|oboist|scroll
      couple|honcho|abbot|obtain|simple
      cutler|hotly|aortae|outset|stool
      cradle|helot|axial|ordure|shale


HISTORY
=======

The |command| command invokes the Python program ``xkcd_password.py``.

The inspiration for the program's purpose is the `XKCD 936`_ “Password
Strength” cartoon.

The application is maintained by Steven Tobin <steven@steventob.in>.

This manual page was written by |author|.

..  |author| replace:: |authorname| |authoremail|
..  |authorname| replace:: Ben Finney
..  |authoremail| replace:: <ben+python@benfinney.id.au>

..  _XKCD 936: https://xkcd.com/936/


..
    Local variables:
    coding: utf-8
    mode: rst
    time-stamp-format: "%:y-%02m-%02d"
    time-stamp-start: "^:Date:[         ]+"
    time-stamp-end: "$"
    time-stamp-line-limit: 20
    End:
    vim: fileencoding=utf-8 filetype=rst :
