Skip to content


Repository files navigation

     mdp - password safe

     mdp [-Vh] [-c config] command [arguments ...]

     mdp is a wrapper around GnuPG and a text editor, it includes a full-
     screen pager with timeout (avoids passwords from lingering on screen) and
     a password generator with profiles.

     The following options are global and apply to all the subsequent

     -c config
             Use an alternate configuration file.

     -V      Print version.

     -h      Print general usage. For command-specific usage, this flag should
             be placed after the command name, for example 'mdp edit -h'.

     mdp add [-h] [-k keyid] [-p profile] [-n count] [-l length] keywords ...

           Add passwords to the end of the password file. This command is an
           alias for 'generate' and 'edit' with the added advantage of not
           requiring any copy-paste. All the arguments to this command will be
           used as prefix in the password file (with the exception of the
           options starting with '-').

           The options for the 'add' command are the same as the 'edit' and
           the 'generate' command.

     mdp edit [-h] [-k keyid]

           Edit the password file (decrypt and re-encrypt after the fact).
           This command creates a temporary file in the same folder as the
           password file and starts the editor, if the file is changed, the
           file is fed to GnuPG when the editor exits.

           The only option for the 'edit' command is:

           -k key_id
                   The argument is a GnuPG key id (8 alpha-numeric
                   characters), it could be used to specify a key id in case
                   it wasn't defined in the configuration file.

     mdp generate [-h] [-p profile] [-n count] [-l length]

           Generate password(s) according to the configuration or command-line
           arguments.  Without profile specified, mdp uses the top-level
           definitions for the character set, password length and count (see
           CONFIGURATION below). All the flags specified on the command-line
           will override the ones specified in the profile or top-level
           definitions. This command can be shortened as 'gen'.

           The options for the generate command are:

           -p profile
                   Choose which profile to use among the ones defined in the
                   configuration file.

           -n count
                   Number of passwords to generate. This command line
                   parameter will override all other values of password_count
                   (global and profile).

           -l length
                   Length of generated passwords (in characters). This command
                   line parameter will override all other values of
                   password_count (global and profile).

     mdp get [-hEr] keywords ...

           Return all the password entries matching the given keywords or
           regexes (if using -E). By default, this command will open a full-
           screen pager to display search results, the time the pager remains
           on screen is adjustable in the configuration file. Note that

           The options for the get command are:

           -E      Use regexes instead of plain text matches (e.g. ^.mail).

           -r      Displays the result without pager, plain terminal dump to
                   stdout.  This option should be used sparingly since the
                   password will linger on screen and in terminal

     mdp prompt [-hE]
           Starts a full-screen pager with search prompt. This command is
           useful to avoid passing the search keywords in the command line
           (and allowing all users in the system to see what passwords are
           requested). Since it uses the default pager, multiple searches can
           be conducted using the '/' key. Any other key will exit the pager,
           it will also exit after a configurable timer. The search keywords
           will be interpreted as regexes if the -E option is used (see mdp

     1. Create a GPG key if needed.

     2. Create a .mdp/config file from the example (with at least gpg_key_id).

     3. Either define EDITOR env variable or add editor to the config file.

     4. Pick a password from randomly generated ones, for example:

                   mdp gen

     5. Run mdp edit and add a line such as:

                   twitter yHVHPnqXyx6qUuki

     6. This is how the Twitter password is requested:

                   mdp get twitter

     This is an alphabetically sorted summary of all the available
     configuration variables and options:

     set backup no
             Define whether we keep a backup every time we edit the password
             file. Default: yes.

     set character_count count
             Define how many characters to randomize per password. Default: 16
             or as defined in the profile.

     set character_set characters
             Define all the characters to use in passwords. Default: all
             alphanumeric (upper and lower case) or as define in the profile.
             The following aliases are supported as shortcuts: $LOWERCASE,

     set editor path
             Command to start the text editor. It's considered better practice
             to define an $EDITOR environment variable. If mdp detects vim, it
             will attempt to add the -n parameter to avoid vim from creating
             swap files.

     set gpg_key_id key_id
             GnuPG key id (default: none). If no key is selected, mdp will
             expect a key specified on the command-line (-k). If no key was
             specified either way, mdp will abort. That this parameter is
             ignored during the decryption phase, GnuPG picks the key based on
             the content of the password file.

     set gpg_path path
             GnuPG absolute path (default: /usr/bin/gpg)

     set gpg_timeout seconds
             Number of seconds to give GnuPG for password and pipe
             interaction. The default value is 10 seconds. This will kill
             GnuPG if forgotten at the password prompt or if it cannot
             communicate with the parent process.

     set password_count count
             Define how many password to show with using 'mdp gen'. Default: 4
             or as defined in the profile.

     set password_file filepath
             Sets the location of the password file. mdp will refuse to use a
             password file with permissions other than 0600. The default value
             for this is ~/.mdp/passwords.

     set timeout seconds
             This variable define how long the pager will display search
             results.  The default value is 10 seconds.  mdp will use your
             default editor (as defined by $EDITOR).

     profile name
             All the variables define below a profile header will be specific
             to this profile. For now only password_count, character_count and
             character_set are valid options.

     The password file should be structured to allow mdp to query it, since it
     works similarly to grep, one line per password is ideal.  For example:

           nameOfServiceA   password1
           anotherService   password2

     The keywords used for search and the passwords can be separated with
     anything except for new-line (\n), allowing services to be found by

           mdp serviceA

     Any convenient number of namespacing hints can be used to add hierarchy,
     the following allows all 'email' passwords to be returned at once:

           email     serviceA       password1
           email     serviceB       password2
           irc       serviceC       password3

     Using '#' in the beginning of a line will avoid mdp from displaying this
     line during searches.  This is particularly useful to add meta data to
     the password file or keep track of previous password without adding noise
     to the output. For example:

           # email services
           serviceA     password1
           serviceB     password2

           # irc servers
           serviceC     password3

     Empty lines are naturally ignored.

     Why not 'shred' the temporary file?
             If the disk can be stolen, it should be encrypted. Shred has
             limited use on most journaled file-systems.

     What if 'root' cannot be trusted?
             The machine cannot be trusted if you cannot trust its

     What if my server is virtualized?
             Same answer as above, if the hosting provider or Iaas cannot be
             trusted, the machine in their facility cannot be trusted.

     EDITOR           The content of this variable will be used as default
                      editor if the configuration does not alter it.

     $HOME/.mdp/config                 Main configuration file for mdp.

     $HOME/.mdp/passwords              Encrypted list of passwords.

     $HOME/.mdp/passwords.bak          This file is a copy of the password
                                       file, before the last edit. The current
                                       password file can be replaced by the
                                       backup to discard the last changes.
                                       Setting 'set backup false' in the
                                       configuration file disables the
                                       creation of the backup file.

     $HOME/.mdp/lock                   This file is created while the password
                                       file is loaded in the editor.  It
                                       avoids two copies of mdp to run at the
                                       same time for the same user.

     gpg(1), sh(1)

     - None that we know of.

     mdp was written by Bertrand Janin <> and is distributed under
     an ISC license (BSD, MIT and OSI compatible).

     A bunch of utility functions are borrowed from OpenBSD and OpenSSH, both
     under ISC and BSD licenses, with copyrights from the following authors:

         Copyright (c) 2004 Ted Unangst and Todd Miller
         Copyright (c) 1998 Todd C. Miller <>
         Copyright (c) 2000 Markus Friedl.  All rights reserved.
         Copyright (c) 2005,2006 Damien Miller.  All rights reserved.

     The random password generator was mostly borrowed from apg (also BSD
     licensed), with the following copyright notice:

         Copyright (c) 1999, 2000, 2001, 2002, 2003
         Adel I. Mirzazhanov. All rights reserved

     The array and xmalloc libraries are taken from tmux, with the following
     copyright notices:

         Copyright (c) 2004 Nicholas Marriott <>
         Copyright (c) 2006 Nicholas Marriott <>