NAME
    kpcli - A command line interface to KeePass database files.

DESCRIPTION
    A command line interface (interactive shell) to work with KeePass
    database files (http://http://en.wikipedia.org/wiki/KeePass). This
    program was inspired by my use of "kedpm -c" combined with my need to
    migrate to KeePass. The curious can read about the Ked Password Manager
    at http://http://kedpm.sourceforge.net/.

USAGE
    Please run the program and type "help" to learn how to use it.

PREREQUISITES
    This script requires these non-core modules:

    "Crypt::Rijndael" - "apt-get install libcrypt-rijndael-perl" on Ubuntu

    "Term::ReadKey" - "apt-get install libterm-readkey-perl" on Ubuntu

    "Sort::Naturally" - "apt-get install libsort-naturally-perl" on Ubuntu

    "Term::ShellUI" - not packaged on Ubuntu

    "File::KeePass" - not packaged on Ubuntu

    Both of the "not packaged" modules above build very cleanly with the
    dh-make-perl tool on Debian and Ubuntu.

    It is also recommended that you install "Term::ReadLine::Gnu" which will
    give you command history and completion functionality. That module is in
    the libterm-readline-gnu-perl package on Ubuntu.

CAVEATS AND WORDS OF CAUTION
    Only interoperability with KeePassX (http://www.keepassx.org/) has been
    tested. File::KeePass seems to have a bug related to some "unknown" data
    that KeePassX stores in the *.kdb file. This program deletes those
    unknown data when saving. Research into libkpass
    http://libkpass.sourceforge.net/) has revealed what File::KeePass
    classifies as "unknown" are the times for
    created/modified/accessed/expires as well as "flags" (id=9), but only
    for groups -- File::KeePass seems to handle those fields just fine for
    entries. I have not found any ill-effect from dropping those fields when
    saving and so that is what kpcli does today to work around this
    File::KeePass bug.

BUGS
  Tab Completion
    Tab completion is not perfect. It has problems with some entries that
    contain spaces, slashes, and/or backslashes. I don't know if I am doing
    something wrong or if Term::ShellUI may have some bugs in its command
    completion code.

  Using Ctrl-D to Exit
    Versions of Term::ShellUI prior to v0.9. do not have the ability to trap
    Ctrl-D exits by the client program. I submitted a patch to remedy that
    and it made it into Term::ShellUI v0.9. Please upgrade if kpcli asks you
    to.

  Multiple Entries or Groups With the Same Name in the Same Group
    This program does not support multiple entries in the same group having
    the exact same name, nor does it support multiple groups at the same
    level having the same name, and it likely never will. KeepassX does
    support those and this program needs to be updated to detect and alert
    when an opened database file has those issues, and maybe refuse to save
    (overwrite) a file that is opened like that. Alternatively, we could
    alert and rename offending groups/entries at load time, by appending
    "-2", "-3", etc.

AUTHOR
    Lester Hightower <hightowe at cpan dot org>

LICENSE
    This program may be distributed under the same terms as Perl itself.

CREDITS
    Special thanks to Paul Seamons, author of File::KeePass, and to Scott
    Bronson, author of Term::ShellUI. Without those two modules this work
    would never have been posible.

CHANGELOG
     2010-Nov-28 - v0.1 - Initial release.
     2010-Nov-28 - v0.2 - Encrypt the master password in RAM.
     2010-Nov-29 - v0.3 - Fixed master password encryption for saveas.
     2010-Nov-29 - v0.4 - Fixed code to work w/out Term::ReadLine::Gnu.
                          Documented File::KeePass v0.1 hierarchy bug.
     2010-Nov-29 - v0.5 - Made find command case insensitive.
                          Bugfix in new command (path regex problem).
     2010-Nov-29 - v0.6 - Added lock file support; warn if a lock exists.
     2010-Dec-01 - v0.7 - Further documented the group fields that are
                           dropped, in the CAVEATS section of the POD.
                          Sort group and entry titles naturally.
     2010-Dec-23 - v0.8 - Worked with File::KeePass author to fix a couple
                           of bugs and then required >=v0.03 of that module.
                          Sorted "/_found" to last in the root group list.
                          Fixed a "database changed" state bug in cli_save().
                          Made the find command ignore entries in /Backup/.
                          Find now offers show when only one entry is found.
                          Provided a patch to Term::ShellUI author to add
                           eof_exit_hook and added support for it to kpcli.
     2011-Feb-19 - v0.9 - Fixed bugs related to spaces in group names as
                           reported in SourceForge bug number 3132258.
                          The edit command now prompts to save on changes.
                          Put scrub_unknown_values_from_all_groups() calls
                           back into place after realizing that v0.03 of
                          File::KeePass did not resolve all of the problems.
     2011-Apr-23 - v1.0 - Changed a perl 5.10+ regex to a backward-compatable
                           one to resolve SourceForge bug number 3192413.
                          Modified the way that the /Backup group is ignored
                           by the find command to stop kpcli from croaking on
                           multiple entries with the same name in that group.
                           - Note: There is a more general bug here that
                                   needs addressing (see BUGS section).
                          An empty title on new entry aborts the new entry.
                          Changed kdb file are now detected/warned about.
                          Tested against Term::ShellUI v0.9, which has my EOF
                           hook patch, and updated kpcli comments about it.
                          Term::ShellUI's complete_history() method was
                           removed between v0.86 and v0.9 and so I removed
                           kpli's call to it (Ctrl-r works for history).
                          Added the "icons" command.
     2011-Sep-07 - v1.1 - Empty DBs are now initialized to KeePassX style.
                          Fixed a couple of bugs in the find command.
                          Fixed a password noecho bug in the saveas command.
                          Fixed a kdb_has_changed bug in the saveas command.
                          Fixed a cli_open bug where it wasn't cli_close'ing.
                          Fixed variable init bugs in put_master_passwd().
                          Fixed a false warning in warn_if_file_changed().
     2011-Sep-30 - v1.2 - Added the "export" command.
                          Added the "import" command.
                          Command "rmdir" asks then deletes non-empty groups.
                          Command "new" can auto-generate random passwords.
     2012-Mar-03 - v1.3 - Fixed bug in cl command as reported in SourceForge
                           bug number 3496544.
     2012-Apr-17 - v1.4 - Added key file support based on a user contributed
                           patch with SourceForge ID# 3518388.
                          Added my_help_call() to allow for longer and more
                           descriptive command summaries (for help command).
                          Stopped allowing empty passwords for export.
     2012-Oct-13 - v1.5 - Fixed "help <foo>" commands, that I broke in v1.4.
                          Command "edit" can auto-generate random passwords.
                          Added the "cls" and "clear" commands from a patch
                           with SourceForge ID# 3573930.
                          Tested compatibility with File::KeePass v2.03 and
                           made minor changes that are possible with >=2.01.
                          With File::KeePass v2.03, kpcli should now support
                           KeePass v2 files (*.kdbx).
     2012-Nov-25 - v1.6 - Hide passwords (red on red) in the show command
                           unless the -f option is given.
                          Added the --readonly command line option.
                          Added support for multi-line notes/comments;
                           input ends on a line holding a single ".".

TODO ITEMS
     Handle Ctrl-C presses (complicated by Term::ShellUI)
      - http://mail.pm.org/pipermail/melbourne-pm/2007-January/002214.html

OPERATING SYSTEMS AND SCRIPT CATEGORIZATION
    Unix-like (written and tested on Ubuntu Linux 10.04.1 LTS).

    UNIX/System_administration

