gnu-pw-mgr(1)

📦 version 2.7.4, in nixos 26.05, nixpkgs unstable

💖 `gnu-pw-mgr(1)` — User Commands 💖

okay so this is gnu-pw-mgr(1), and yes it lives in the User Commands corner of the manual, and yes it's literally the moment your whole "one password for everything" era ends. buckle up bestie 💅

🎀 NAME 🎀

gnu-pw-mgr — derive a password from an id

✨ SYNOPSIS ✨

gnu-pw-mgr [-flags] [-flag [value]] [--option-name[[=| ]value]] [ <pw-id> ]

🦋 DESCRIPTION 🦋

So your password id should contain a fairly consistent permutation of the URL you're logging in to. why "fairly"? because you might wanna vary your financial institutions differently than your newspaper 📰, or you might need multiple credentials for the same domain. Either way, a password id is formed by surrounding the domain name with unlikely prefixes, suffixes and punctuations. iconic behavior, honestly.

Only the passwords for one password id are ever printed. If the command line contains multiple operands (arguments after the options), then they are assembled into one password id with space characters separating the original operands. One password is printed for each seed stored in the password configuration file.

One password is printed for every configured seed value with a matching --shared option state ✨. Seed values are added by specifying just the --tag and --text options, with or without the --shared option. When passwords are printed, the tag is also printed in plain text.

Passwords are changed by specifying the -r or --rehash option with a new numeric value. The day this happens will be noted in the password configuration file and printed in the password header 🗓️.

Password ids are never stored anywhere. no cap, they just don't exist on disk.

Please be sure to read the "Warnings" section in the full documentation 👀.

NOTE: the --load-opts option is supported by the option processing library. This program actually prohibits its usage. The password configuration database is normally found in a standard location. It may be overridden at invocation time by the --config-file option. Using --load-opts on the command line will lead to a conflict error. 🚨

Example usage can be seen in the example section below.

🌸 OPTIONS 🌸

🍓 Options for adding and removing seeds in the configuration file.

The --text option or the --tag option (when by itself) tell the program to manage password "seeds" in its database (configuration file). Both options together add a new seed, and --tag, by itself on the command line, removes a seed. 💀

--seed=seed — define a seed for a series of passwords.
- This option is not a command line option. It is also the only option that is directly processed from the config file.

The seed values consist of four named parts (sub-options):

tag — These are displayed next to each displayed password to help identify them. 🏷️
text — This is not displayed, but is used for the SHA initial value. This may be arbitrarily long.
ver — The version of gnu-pw-mgr used to initially store the seed. This is used to determine the password tweaking algorithm to use when the generated password does not meet the site criteria (@pxref{gnu-pw-mgr password-options,, the password character class option}). On rare occasions, new character class restrictions may cause a change in the algorithm used to tweak passwords. When this is done, the old algorithm is still used to tweak passwords from the older seeds.
shared — The presence of this sub-option specifies that the seed is only to be used with password ids that are also marked as --shared. Without this sub-option, the seed is only used with password ids that are not marked as --shared. 🫶

The way to change a password is to specify the rehash count. It defaults to 10007. You can determine the current value with the --status option.

Specify only the --tag and --text (and maybe --shared) command line options and the program will initialize or insert a new value into the configuration file. Specify only the tag and no other command line arguments, and the associated seed entry will be removed. All passwords using that seed will become unavailable. You cannot remove the last seed. 😭

-t tag, --tag=tag — seed tag. This option may not be preset with environment variables or in initialization (rc) files. This option must not appear in combination with any of the following options: login-id, length, cclass, rehash, specials, no-header, select-chars, confirm, status, delete.
- The tag for a seed to be added to or removed from the config file. The use depends on whether or not there is a --text option.
-s text, --text=text — seed text. This option may not be preset with environment variables or in initialization (rc) files. This option must appear in combination with the following options: tag.
- The text for a password seed to be added to the config file. This text cannot include the 7 character sequence </text>. There must always be at least one. Multiple text seeds will cause multiple passwords to be printed out. 🖨️
- This text must be at least 64 characters long. The expectation is you will write a sentence or two that you can easily remember, including any capitalization, punctuation and spacing. You should include some non-alphabetic, non-digit characters here and there to make a dictionary attack more difficult. But if you need to reconstruct this, you need to remember them. 🧠
- If the text is shorter than 64 characters, it will be padded out. In such a case, you will need to save the configuration file some place secure or it will be extremely difficult to reconstruct it, should that become necessary. 🔐
- The original expectation was that passwords would be updated on an occasional basis. Now that I have over 100 login credentials, it is clearly infeasible to go around and update them all. Instead, I have to decide which are important to update and use the --rehash option to change the rehash count. The date of the last rehash count change is recorded with the password id options.
--shared, --no-shared — shared tag. The no-shared form will disable the option. This option may not be preset with environment variables or in initialization (rc) files.
- If this option is used in conjunction with the text option, that seed is marked as a shared password seed and derived passwords are only printed for password ids that have been marked as shared. When used in conjunction with a password id, then the password id will be marked as a shared. Passwords will only be printed for seeds and ids that have matching "shared" settings.
--default-cclass=cclass, --no-default-cclass — set default character classes. The no-default-cclass form will disable the option. This option may not be preset with environment variables or in initialization (rc) files.
- When present on the command line by itself, the value is stashed in the configuration file and used in future invocations of "gnu-pw-mgr".
- The GNU password manager defaults to requiring one alphabetic character (upper or lower case) and one digit. Most passwords are required to have something more complicated. Once this option has been provided, the new default will be applied whenever a new password identifier is detected. This detection is based on not finding any attributes stored in the configuration file. This means that if you rely on all defaults for some login (you never provided any "password options" for the id), the generated password might change. 😬
- You cannot adjust previous values. The classes you select will become the default character classes from then on. Previous password ids will continue using the value assigned when the password was first created.

👑 Options for specifying password attributes.

The --cclass, --length, --tag, --shared and --specials options are stored in the configuration file. They are associated with a password ID via a clipped sha check sum of the id. They will be recalled the next time that id is used. ✨

-i string, --login-id=string — a reminder of your login id. This option may not be preset with environment variables or in initialization (rc) files.
- It is sometimes difficult to remember your login name for a given site. Or even, perhaps, if you have ever set up an account on a particular site. By specifying this option, you will know both that you have set it up and you will have a reminder what your login name is. Avoid using your real login name. 🙈
- Also, there are now some sites that send password credentials to a validation domain that is common among several domains. Since this application forces you to use different passwords for different domains and these domains force you to use the same password for different domains, this option solves the irresistable force and immovable object dilemma. For each of the dependent domains, specify this option that will remind you of the correct password id.
- The login-id has no effect on the final password, so it may be specified or altered at any time.
-l number, --length=number — sets password length. This option may not be preset with environment variables or in initialization (rc) files. This option takes an integer number as its argument. The value of number is constrained to being:
- in the range 4 through 128
- The default number for this option is: 16
- Some web sites are more restrictive. Some are more generous. Use of this option requires a <pw-id> operand.
- Password lengths of 4 through 7 characters are limited to "pin" numbers. "pin" numbers are 4 or more digits. All other passwords must be at least 8 characters long. The default length is 16. Use at least 24, if you can. 💪
-c set-member, --cclass=set-member — password character class. This option may not be preset with environment variables or in initialization (rc) files. This option takes a keyword as its argument list. Each entry turns on or off membership bits. The bits are set by name or numeric value and cleared by preceding the name or number with an exclamation character ('!'). They can all be cleared with the magic name none and they can all be set with all. A single option will process a list of these values. The available keywords are:
- alpha
- upper
- lower
- digit
- special
- no-special
- no-alpha
- no-triplets
- no-sequence
- pin
- alnum
- two-upper
- two-lower
- two-digit
- two-special
- or their numeric equivalent.
- The default set-member for this option is: alpha + digit
- This option augments or specifies which character classes either must or must not appear in the final password.

…and that's where this part lands, but there's still so much more coming 💜

Some sites are weird about special characters — some flat-out ban them, some require them, and some require them but only, like, the specific ones they've decided are acceptable 💀. If they're banned, hit it with no-special and your special characters get swapped out for digits. If special is specified specifically, then when there's no '+' or '/' in there (or their alternates), one character gets replaced with a hyphen. And yeah, you can swap in other characters for those three special ones with the --specials option. 🎀

✨ the keywords, explained (iykyk) ✨

upper — bestie there must be at least one upper case letter. non-negotiable.
lower — at least one lower case letter. And if you use this and upper together, you need one of each.
alpha — at least one alphabetic character, upper or lower, dealer's choice. If either upper or lower is specified, this attribute is a total no-op (it's giving redundant 💅).
no-alpha — alphabetic characters are banned, periodt. This conflicts with upper, lower and alpha.
digit — at least one decimal digit character, no cap.
no-triplets — when three characters in a row are the same, the third one gets fiddled with. Letters are changed to the next letter and z becomes a. Digits are handled similarly. Special characters are replaced with the third possible special character (-, unless modified with --specials). (Yes, there are a few such sites. 😭)
special — the password must contain at least one special character (a non-alphabetic, non-digit character).
no-special — the password must not contain any characters that aren't alphabetic or decimal digits. zero. zilch.
no-sequence — the password must not contain a consecutive sequence of three or more characters. rude but okay.
pin — the password is all digits, a Personal Identification Number. It's an abbreviation for no-alpha + no-special + digit.
alnum — abbreviation for alpha + digit.
two-* — two of a particular character class are required. Specifying this implies "at least one of" the specified type. Two upper case, lower case, punctuation (special) and digit characters may be specified this way. two-alpha is not supported, so don't even try it 🔥.

-r number, --rehash=number — change the password rehash count. This option may not be preset with environment variables or in initialization (rc) files. It takes an integer number as its argument, and the value of number is constrained to being:

  in the range  1 through 100000

Passwords are created with the SHA256 hash of the "seed string", the password id, and the tag text associated with the seed. The result is then "rehashed" with the pbkdf2 function. By default, this is done 10007 times. You can change that by specifying a different count between 1 and 100,000. You can change it either directly with a count or by prefixing a number with a '+' or '-' character — the prefix will cause the previous value to be adjusted. Changing the count will change the password and will mark the entry with the date of the most recent password change. 🗓️

Please see RFC 2898 for a specification of the PBKDF2 (Password-Based Key Derivation Function version 2) function. ngl, it's a whole read, but it's there.

--use-pbkdf2=number, --no-pbkdf2 — rehash password with PKCS#5 PBKDF2. The no-pbkdf2 form will disable the option. This option is enabled by default. This option may not be preset with environment variables or in initialization (rc) files. It takes an integer number as its argument, and the default number for this option is:

This option is for internal use only. The rehash count is stored in the configuration file as a "pbkdf2" value. 🙈

--specials=string — set alternate special characters. This option may not be preset with environment variables or in initialization (rc) files. The default string for this option is:

/+-

The computed password is a base64 encoding of a sha256 hash of various inputs. Base64 encoding uses '+' and '/' characters. However, when this program is required to have at least one special character in the result, and neither the '+' nor '-' get encoded, one character will be replaced with a hyphen (-).

Some web sites require particular special characters in their passwords that do not include these three default characters. For those passwords, specify this option with exactly three characters in the string argument. They will be used to replace the three characters above. The first two may be the same, but the third must be different from the first two. This option is accepted, but serves no purpose if no-special has been specified in the --cclass option. 💅

🎀 Options for management and output format 🎀

-H, --no-header — omit printing the password headers. This option may not be preset with environment variables or in initialization (rc) files.

By default, the output includes column headers. For confirmation output, the two values will have column labels, and for password output, it will contain any login hint and the date the last time the --rehash count was changed. (Password was changed, bestie.)

Suppressing it is intended for automated logins. The login name hint will not be provided, but the tag is printed. 🏷️

--select-chars=string — select only certain bytes of a password. This option may not be preset with environment variables or in initialization (rc) files.

There exists at least one web site that asks you to enter just some of the password characters, like the second, tenth and sixteenth. With long, memorable-resistant passwords, this can be difficult to do 😭. For such web sites, provide this option with the string "2,10,16" as the option argument. The characters to select are space or comma separated values. The result cannot be longer than the original password.

-C string, --confirm=string — confirmation question answers (see man page). This option may not be preset with environment variables or in initialization (rc) files.

Some web sites use "confirmation questions" that, supposedly, only you know the answer to. Unfortunately, these are often times questions that can be researched by others, or they can be questions that you have forgotten the answers to or may have multiple answers for. The net result is that you are locked out. 💀 This option makes it easy to get consistent answers to these questions and have these answers be different for every web site, just like your password.

Providing this option will cause the argument to be merged into the hash source (changing the resulting password). Exactly 12 letters will be extracted from the hash and converted to lower case. The string argument to this option should be the last word or two from the question, yielding an easy-to-remember way of obtaining a consistent answer to these inscrutable questions.

You will need to update your confirmation question answers when you update your password seed. However, since that can be highly inconvenient also, this option will print TWO results. The first will be dependent on the current password hash, the second will depend only on the confirmation question and password id. Consequently, the second one will be stable going forward. The first answer is now deprecated. ⚠️

--old-confirm=string — out-of-date confirmation question answers. This option may not be preset with environment variables or in initialization (rc) files.

Use this method of answering confirmation questions only if you have to. When your password changes, this will change, too. Inconvenient.

NOTE: THIS OPTION IS DEPRECATED 🚫

-S, --status — show status of a password id. This option may not be preset with environment variables or in initialization (rc) files.

Show all the modified password attributes for a password id. If there are no special attributes, the word default is printed. No password id is invalid, but some may have all default values — consequently there is no special information kept about it.

Command line options will affect the output, but will not be stored for future use. 👑

-d, --delete — remove a password id entry. This option may not be preset with environment variables or in initialization (rc) files.

This will print out the attributes associated with a particular password id and remove them from the configuration file. bye felicia 🫶

--domain=domain — a reminder of domains used for password id. This option may appear an unlimited number of times. This option may not be preset with environment variables or in initialization (rc) files.

If you create a lot of passwords, it is easy to forget which domains have an associated password. You do not want to specify a password id, merely note the domains for which you have a password id. With well over 100 passwords, I found I need to be able to know which need to be updated occasionally. This option will cause a separate text database to be updated with a domain name and an update date. With a single hyphen as the option argument, that database will be printed out in chronological order. ⭐

--config-file=config-file — specify configuration file. This option may not be preset with environment variables or in initialization (rc) files.

If you need an alternate location for storing your password seed files, use this option. It must be specified on the command line every time it is needed. You are responsible to ensure that the directory already exists. The file will be left read-only when gnu-pw-mgr exits. The containing directory permissions will not be checked or altered. 🔒

🌈 Options supported by the AutoOpts option library 🌈

-h, --help — display usage information and exit.
-M, --more-help — pass the extended usage information through a pager.
--load-opts=cfgfile, --no-load-opts — load options from cfgfile. The no-load-opts form will disable the loading of earlier config/rc/ini files. --no-load-opts is handled early, out of order. 😳
-v [{v|c|n --version [{v|c|n}]}] — output version of program and exit. The default mode is v, a simple version. The c mode will print copyright information and n will print the full copyright notice.

🦋 OPTION PRESETS 🦋

Any option that is not marked as not presettable may be preset by loading values from configuration ("RC" or ".INI") file(s). ✨

📁 FILES 📁

See OPTION PRESETS for configuration files.

💖 EXAMPLES 💖

Okay so bestie, listen — before you can print literally any password, you gotta initialize the database with at least one seed first. No seed, no password, no vibes. ✨

gnu-pw-mgr --tag "first-seed-tag" --text "This is only a 'test'.  Were it real,
you _would_ likely know?"

These two strings, plus a password id, get cooked together into a sha256 hash code password. So like… now you can actually print one 🎀

gnu-pw-mgr --login-id "user-name" --length 32 \
    --cclass=upper,lower,digit,special \
    my example.com

In this example the password id is the string "my example.com" — yes, with a whole space in it. That space character gets inserted between the command line operands, that's just how it goes. The options get associated with this id via another sha256 sum of just the id. Iconic, honestly.

The "user-name" would typically be either your actual user name for the site, or literally anything that could readily remind you of the login id. If you omit it — fine — just do not forget it, that's the whole deal. 🙈

The length specifies the maximum length allowed for a password on the site. You will get a password of that length. And --cclass defines the allowed and/or required character class(es) for the passwords for the site.

So with the above seed and invocation, you will see printed out exactly this:

seed-tag     login id hint: user-name   pw:
first-seed-tag iQiF1g5aLQ0JqFIUbR/svpTS+F/PCeoy

Henceforth typing just gnu-pw-mgr my example.com will always yield this output. Periodt. 💅 The options above are now associated with the password id via a hash code. The gnu-pw-mgr database (either ~/.local/gnupwmgr.cfg or ~/.gnupwmgrrc, but the former preferred) will now be this — hash code abbreviated:

<seed>
  <tag>first-seed-tag</tag>
  <text>This is only a 'test'.  Were it real,
you _would_ likely know?</text>
</seed>
<program per_pw_id>
<pwtag id="HASH">
  cclass = =alpha + upper + lower + digit + special
</pwtag>
<pwtag id="HASH">length = 32</pwtag>
<pwtag id="HASH">login-id = 'user-name'</pwtag>

🚪 EXIT STATUS 🚪

One of the following exit values will be returned:

0 (EXIT_SUCCESS) — successful program execution. slay 🎉
1 (EXIT_INVALID) — the option/argument configuration is invalid
2 (EXIT_NO_MEM) — insufficient memory
3 (EXIT_BAD_USER) — no password entry for current user
4 (EXIT_HOMELESS) — home directory could not be found
5 (EXIT_PERM) — config file improperly protected
6 (EXIT_NO_CONFIG) — config file missing
7 (EXIT_BAD_CONFIG) — cannot update config file
8 (EXIT_NO_SEED) — no seeds were specified in the config file
9 (EXIT_BAD_SEED) — The seed value was invalid
10 (EXIT_BAD_SELECT_CHARS) — the list of characters for the --select-chars option is bad
11 (EXIT_NO_PWID) — no password id was specified
16 (EXIT_CODING_ERROR) — There is a coding error that should be reported
66 (EX_NOINPUT) — A specified configuration file could not be loaded.
70 (EX_SOFTWARE) — libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you. 🫶

✍️ AUTHORS ✍️

Written by Bruce Korb.

🐛 BUGS 🐛

Please send bug reports to: bkorb@gnu.org

📝 NOTES 📝

So this program specifies its own configuration file and disallows the use of any other. Rude? Maybe. Correct? Absolutely. This file should be modified by running this program, not by editing it. And heads up: the --seed and --load-opts options cannot be specified on the command line, and the --seed option is only recognized in a configuration file. iykyk 💀

Password ids should have some always-used prefix and/or suffix glued onto a domain name, or some trivial permutation of the domain name. If you forget your password id, then the associated password is irretrievably lost — like, gone gone. 😭 The prefix and suffix should be easily remembered. And if you do not add a prefix or suffix and the configuration file becomes compromised, then you have lost the keys to all your passwords, because it becomes trivial to guess password ids. That's the plot twist nobody wants.

For example, always prepending mine to a domain would yield mine_example.com for your password id at example.com. Password ids are not stored anywhere. Wild, I know. 🦋

This manual page was AutoGen-erated from the gnu-pw-mgr option definitions.

That's the whole page bestie — footer and all: this is gnu-pw-mgr version 2.7.4, dated 2020-09-30, filed under gnu-pw-mgr(1). Go forth and never forget your password id, fr fr 💜🌸

📦 where this page comes from

nixos 26.05: gnu-pw-mgr 2.7.4
nixpkgs unstable: gnu-pw-mgr 2.7.4
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms