GuidoBerhoersterguido+pwm@berhoerster.name17 September, 2017pwm1User Commandspwmpassword managerpwmpassword_filedatabase_fileDescriptionThe pwm utility is a password manager which
stores passwords and associated metadata in an encrypted database protected
by a master password. It offers both a text-based user interface for
interactive use as well as a non-interactive mode. The database uses the
PasswordSafe database version 3 file format and thus provides
interoperabity with other password managers using the same format.After opening an existing database or creating a new one,
pwm provides commands to create, modify, delete, and
display password database entries which may be organized in groups. The
contents of a field of a given entry can also be piped to an external
command such as the pwm-clip1 utility in order to copy the
content of the username or password field of an entry to the
clipboard.If specified, pwm will open or create
database_file instead of the user's default
database.pwm must be run with a locale which uses the UTF-8
character encoding.Output formatThe show and info commands
display fields by printing the field name followed by a colon, one or
more space characters and the field's verbatim content to the standard
output stream. Field content may contain newlines, non-printable and/or
control characters.If running in interactive mode, the list,
show and info will display
the results on a page-by-page basis using an internal pager.The pipe prints the verbatim field content to the
standard input stream of the given command.Error messages are printed to the standard error stream.OptionsThe following options are supported:password_fileRead the master password from the first line of
password_file.Treat the database as read-only and disallow any modifications
and write operations.UsageIf stdin is connected to a terminal pwm will run in interactive mode
and prompt the user for the master password unless
password_file is specified via the
option. After successfully opening the password
database the user will be prompted for a command.When running in non-interactive mode a file containing the master
pasword must be specified via the option and after
successfully opening the password database, pwm will execute commands read
from stdin until either an error occurrs or end-of-file is reached.pwm operates on a copy of the password database
in memory, any changes must be explicitly written back to the database
using the write command.IDsDatabase entries are referred to by an ID value which is a
positive integer value that is guaranteed to be unqiue during the run
time of the pwm utility.FieldsThe following entry fields are supported:
Fields and their identifiersFieldField IdentifierGroupgroupTitletitleUsernameusernamePasswordpasswordNotesnotesURLurlCreation TimectimeModification Timemtime
Other, existing fields specified by the PasswordSafe file format
will be preserved but cannot be displayed or modified.CommandsEach command must appear on a seperate line terminated by a newline
character. The command and its arguments are seperated by whitespace,
i.e. one or more space or tab characters. If an argument contains
whitespace characters it must either be quoted by encosing it in single
or double quote characters or each whitespace character must be preceded
by a backslash character. Arguments quoted with a single or double quote
character preserve the literal values of all characters with the
exception of the backslash character which can be used to escape the
respective quoting character. Two consecutive backslash characters yield
a literal backslash within both quoted and unquoted arguments. A line
must not end in a single backslash character, any other backslash
characters are ignored.If an error occurrs while parsing or executing a command,
pwm will terminate when running in non-interactive
mode. In interactive mode it will print an error message and prompt the
user for the next command. The following commands are supported:List entrieslistfield~regexlsfield~regexList password database entries. If one or more filter
expressions are specified, limit the displayed entries to those
whose field content matches the extended
regular expression regex.Create entrycreatefield=valuecfield=valueCreate a new entry assigning each given
field to the corresponsing
value.If no fields are specified in interactive mode,
pwm will prompt the user for the content of
each field.Modify entrymodifyidfield=valuemidfield=valueModify an existing entry identified by
id assigning each given
field to the corresponsing
value.If no fields are specified and pwm is
running in interactive mode, it will prompt the user for the
content of each field, allowing him to edit any previous
content.Remove entryremoveidrmidRemove an existing entry identified by
id.Display entry fieldsshowidfieldsidfieldDisplay each field of the entry
identified by id. If no field is
specified, display all fields except the password field.Pipe entry fields to an external commandpipeidfieldcommandpidfieldcommandPipe the content of each given
field of the entry identified by id to
command which must be a single argument. The command is executed by
invoking the sh utility with the -c
option and command as its option
argument, thus special care should be applied to quoting command.
See the sh1 manual page for
details.Create empty groupcreategroupnamecgnameCreate a new empty group named
name.In interactive-mode the name
argument is optional, if it is not specified pwm
will prompt the user for it.Remove empty groupremovegroupnamergnameRemove the empty group named
name.Generate a random passwordgeneratepasswordid
len=n
chars=n:chars
charclass=n:classgpid
len=n
chars=n:chars
charclass=n:classRandomly generate a new password according to the specified
constraints. The len argument sets the length of
the generated password to n characters.
The chars argument constrains the password to
n from the set of characters
chars. Similarly, the
charclass argument to
n characters from the extended regular
expression character class class.
Multiple char and charclass
arguments may be specified, in which case the generated passwords
match all of them.Change the master passwordchangepasswordchChange the master password.Display help texthelpcommandhcommandDisplay a summary of all commands or usage information for
the specified command.Show metadata informationinfoiDisplay metadata information such as the user who last wrote
to the database, the time when the database was last written to,
and the host on which the password database was last written
to.Display status messagesstatustRedisplay any error message from the previous command and
whether there are unsaved changes.Write databasewritewWrite all changes back to the password database.Quitquitqend-of-fileQuit pwm. If running in interactive mode
and there are unsaved changes, pwm will not
terminate but display a warning message. If the quit command is
invoked twice consecutively, pwm will discard
unsaved changes and terminate.Quit and discard unsaved changesQuitQQuit pwm and discard any unsaved changes
without a warning.File FormatThe canonical description of the file format is included with the
distribution of the pwsafe1 utility.Environment VariablesLANGLC_ALLSee locale5LOGNAMEThe name of the logged in user which is recorded when writing
the password databaseExit StatusThe following exit values are returned:0Command successfully executed.1An unspecified error has occured.2Invalid command line options were specified.Asynchronous EventsSIGINTSIGHUPSIGTERMIf there are changes since the database was last written and
pwm is running in interactive mode, it
automatically writes a copy of the current database to the file
~/.pwm/autosave.psafe3 which may be used for
recovery later.Files~/.pwm/pwm.psafe3default password database~/.pwm/autosave.psafe3automatic copy of the password database after receiving a fatal
signal in interactive modeSee Alsopwm-clip1,
pwsafe1,
sh1,
locale5,
regex5,