<?xml version="1.0"?>
<!--

Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>

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.

-->
<refentry xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
  <info>
    <author>
      <personname>
        <firstname>Guido</firstname>
        <surname>Berhoerster</surname>
      </personname>
      <email>guido+pwm@berhoerster.name</email>
      <personblurb/>
    </author>
    <date>6 September, 2017</date>
  </info>
  <refmeta>
    <refentrytitle>pwm</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source"/>
    <refmiscinfo class="version"/>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>pwm</refname>
    <refpurpose>password manager</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>pwm</command>
      <arg choice="opt">
        <option>-P</option>
        <replaceable>password_file</replaceable>
      </arg>
      <arg choice="opt">
        <replaceable>database_file</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>The <command>pwm</command> 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.</para>
    <para>After opening an existing database or creating a new one,
    <command>pwm</command> 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, e.g. in order to copy the content of the username or password
    field of an entry to the clipboard.</para>
    <para>If specified, <command>pwm</command> will open or create
    <replaceable>database_file</replaceable> instead of the user's default
    database.</para>
    <para><command>pwm</command> must be run with a locale which uses the UTF-8
    character encoding.</para>
    <refsect2>
      <title>Output format</title>
      <para>The <command>show</command> and <command>info</command> 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.</para>
      <para>If running in interactive mode, the <command>list</command>,
      <command>show</command> and <command>info</command> will display
      the results on a page-by-page basis using an internal pager.</para>
      <para>The <command>pipe</command> prints the verbatim field content to the
      standard input stream of the given command.</para>
      <para>Error messages are printed to the standard error stream.</para>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>Options</title>
    <para>The following options are supported:</para>
    <variablelist>
      <varlistentry>
        <term>
          <option>-P</option>
          <replaceable>password_file</replaceable>
        </term>
        <listitem>
          <para>Read the master password from the first line of
          <replaceable>password_file</replaceable>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Usage</title>
    <para>If stdin is connected to a terminal pwm will run in interactive mode
    and prompt the user for the master password unless
    <replaceable>password_file</replaceable> is specified via the
    <option>-P</option> option. After successfully opening the password
    database the user will be prompted for a command.</para>
    <para>When running in non-interactive mode a file containing the master
    pasword must be specified via the <option>-P</option> 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.</para>
    <para><command>pwm</command> operates on a copy of the password database
    in memory, any changes must be explicitly written back to the database
    using the write command.</para>
    <refsect2>
      <title>IDs</title>
      <para>Database 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.</para>
    </refsect2>
    <refsect2>
      <title>Fields</title>
      <para>The following entry fields are supported:</para>
      <table xml:id="field-table">
        <title>Fields and their identifiers</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <thead>
            <row>
              <entry>Field</entry>
              <entry>Field Identifier</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>Group</entry>
              <entry>group</entry>
            </row>
            <row>
              <entry>Title</entry>
              <entry>title</entry>
            </row>
            <row>
              <entry>Username</entry>
              <entry>username</entry>
            </row>
            <row>
              <entry>Password</entry>
              <entry>password</entry>
            </row>
            <row>
              <entry>Notes</entry>
              <entry>notes</entry>
            </row>
            <row>
              <entry>URL</entry>
              <entry>url</entry>
            </row>
            <row>
              <entry>Creation Time</entry>
              <entry>ctime</entry>
            </row>
            <row>
              <entry>Modification Time</entry>
              <entry>mtime</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>Other, existing fields specified by the PasswordSafe file format
      will be preserved but cannot be displayed or modified.</para>
    </refsect2>
    <refsect2>
      <title>Commands</title>
      <para>Each 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.</para>
      <para>If an error occurrs while parsing or executing a command,
      <command>pwm</command> 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:</para>
      <variablelist>
        <varlistentry>
          <term>List entries</term>
          <listitem>
            <cmdsynopsis>
              <command>list</command>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>~<replaceable>regex</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>ls</command>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>~<replaceable>regex</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>List password database entries. If one or more filter
            expressions are specified, limit the displayed entries to those
            whose <replaceable>field</replaceable> content matches the extended
            regular expression <replaceable>regex</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Create entry</term>
          <listitem>
            <cmdsynopsis>
              <command>create</command>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>=<replaceable>value</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>c</command>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>=<replaceable>value</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Create a new entry assigning each given
            <replaceable>field</replaceable> to the corresponsing
            <replaceable>value</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Modify entry</term>
          <listitem>
            <cmdsynopsis>
              <command>modify</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>=<replaceable>value</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>m</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>=<replaceable>value</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Modify an existing entry identified by
            <replaceable>id</replaceable> assigning each given
            <replaceable>field</replaceable> to the corresponsing
            <replaceable>value</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Remove entry</term>
          <listitem>
            <cmdsynopsis>
              <command>remove</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>rm</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Remove an existing entry identified by
            <replaceable>id</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Display entry fields</term>
          <listitem>
            <cmdsynopsis>
              <command>show</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>s</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                <replaceable>field</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Display each <replaceable>field</replaceable> of the entry
            identified by <replaceable>id</replaceable>. If no field is
            specified, display all fields except the password field.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Pipe entry fields to an external command</term>
          <listitem>
            <cmdsynopsis>
              <command>pipe</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="plain" rep="repeat">
                <replaceable>field</replaceable>
              </arg>
              <arg choice="plain">
                <replaceable>command</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>p</command>
              <arg choice="plain">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="plain" rep="repeat">
                <replaceable>field</replaceable>
              </arg>
              <arg choice="plain">
                <replaceable>command</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Pipe the content of each given
            <replaceable>field</replaceable> of the entry identified by id to
            command which must be a single argument. The command is executed by
            invoking the <command>sh</command> utility with the <arg>-c</arg>
            option and <replaceable>command</replaceable> as its option
            argument, thus special care should be applied to quoting command.
            See the <citerefentry><refentrytitle>sh</refentrytitle>
            <manvolnum>1</manvolnum></citerefentry> manual page for
            details.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Create empty group</term>
          <listitem>
            <cmdsynopsis>
              <command>creategroup</command>
              <arg choice="plain">
                <replaceable>name</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>cg</command>
              <arg choice="plain">
                <replaceable>name</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Create a new empty group named
            <replaceable>name</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Remove empty group</term>
          <listitem>
            <cmdsynopsis>
              <command>removegroup</command>
              <arg choice="plain">
                <replaceable>name</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>rg</command>
              <arg choice="plain">
                <replaceable>name</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Remove the empty group named
            <replaceable>name</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Generate a random password</term>
          <listitem>
            <cmdsynopsis>
              <command>generatepassword</command>
              <arg choice="opt">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt">
                len=<replaceable>n</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>gp</command>
              <arg choice="opt">
                <replaceable>id</replaceable>
              </arg>
              <arg choice="opt">
                len=<replaceable>n</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
              </arg>
              <arg choice="opt" rep="repeat">
                charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Randomly generate a new password according to the specified
            constraints. The <literal>len</literal> argument sets the length of
            the generated password to <replaceable>n</replaceable> characters.
            The <literal>chars</literal> argument constrains the password to
            <replaceable>n</replaceable> from the set of characters
            <replaceable>chars</replaceable>. Similarly, the
            <literal>charclass</literal> argument to
            <replaceable>n</replaceable> characters from the extended regular
            expression character class <replaceable>class</replaceable>.
            Multiple <literal>char</literal> and <literal>charclass</literal>
            arguments may be specified, in which case the generated passwords
            match all of them.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Change the master password</term>
          <listitem>
            <cmdsynopsis>
              <command>changepassword</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>ch</command>
              <sbr/>
            </cmdsynopsis>
            <para>Change the master password.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Display help text</term>
          <listitem>
            <cmdsynopsis>
              <command>help</command>
              <arg choice="opt">
                <replaceable>command</replaceable>
              </arg>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>h</command>
              <arg choice="opt">
                <replaceable>command</replaceable>
              </arg>
              <sbr/>
            </cmdsynopsis>
            <para>Display a summary of all commands or usage information for
            the specified <replaceable>command</replaceable>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Show metadata information</term>
          <listitem>
            <cmdsynopsis>
              <command>info</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>i</command>
              <sbr/>
            </cmdsynopsis>
            <para>Display 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.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Display status messages</term>
          <listitem>
            <cmdsynopsis>
              <command>status</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>t</command>
              <sbr/>
            </cmdsynopsis>
            <para>Redisplay any error message from the previous command and
            whether there are unsaved changes.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Write database</term>
          <listitem>
            <cmdsynopsis>
              <command>write</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>w</command>
              <sbr/>
            </cmdsynopsis>
            <para>Write all changes back to the password database.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Quit</term>
          <listitem>
            <cmdsynopsis>
              <command>quit</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>q</command>
              <sbr/>
            </cmdsynopsis>
            <para>Quit <command>pwm</command>.  If running in interactive mode
            and there are unsaved changes, <command>pwm</command> will not
            terminate but display a warning message. If the quit command is
            invoked twice consecutively, <command>pwm</command> will discard
            unsaved changes and terminate.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Quit and discard unsaved changes</term>
          <listitem>
            <cmdsynopsis>
              <command>Quit</command>
            </cmdsynopsis>
            <cmdsynopsis>
              <command>Q</command>
              <sbr/>
            </cmdsynopsis>
            <para>Quit <command>pwm</command> and discard any unsaved changes
            without a warning.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>File Format</title>
    <para>The canonical description of the file format is included with the
    distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
    <manvolnum>1</manvolnum></citerefentry> utility.</para>
  </refsect1>
  <refsect1>
    <title>Environment Variables</title>
    <variablelist>
      <varlistentry>
        <term>
          <literal>LANG</literal>
        </term>
        <term>
          <literal>LC_ALL</literal>
        </term>
        <listitem>
          <para>See <citerefentry><refentrytitle>locale</refentrytitle>
          <manvolnum>5</manvolnum></citerefentry></para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <literal>LOGNAME</literal>
        </term>
        <listitem>
          <para>The name of the logged in user which is recorded when writing
          the password database</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Exit Status</title>
    <para>The following exit values are returned:</para>
    <variablelist>
      <varlistentry>
        <term>0</term>
        <listitem>
          <para>Command successfully executed.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>1</term>
        <listitem>
          <para>An unspecified error has occured.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>2</term>
        <listitem>
          <para>Invalid command line options were specified.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Asynchronous Events</title>
    <variablelist>
      <varlistentry>
        <term><literal>SIGINT</literal></term>
        <term><literal>SIGHUP</literal></term>
        <term><literal>SIGTERM</literal></term>
        <listitem>
          <para>If there are changes since the database was last written and
          <command>pwm</command> is running in interactive mode, it
          automatically writes a copy of the current database to the file
          <filename>~/.pwm/autosave.psafe3</filename> which may be used for
          recovery later.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Files</title>
    <variablelist>
      <varlistentry>
        <term><filename>~/.pwm/pwm.psafe3</filename></term>
        <listitem>
          <para>default password database</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>~/.pwm/autosave.psafe3</filename></term>
        <listitem>
          <para>automatic copy of the password database after receiving a fatal
          signal in interactive mode</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>See Also</title>
    <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sh</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>locale</refentrytitle>
      <manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>regex</refentrytitle>
      <manvolnum>5</manvolnum></citerefentry>,
      <link xlink:href="https://pwsafe.org/"/></para>
  </refsect1>
</refentry>