passhole()

SYNOPSIS

ph [OPTIONAL ARGS] [COMMAND] [COMMAND OPTIONS] [COMMAND ARGS]

COMMANDS

show [-h] [--field FIELD] PATH
    Show the contents of an entry, where PATH is the full path to the entry. The password field is spoilered and must be highlighted to reveal the plaintext password. Use --field FIELD to print only the specified field, where FIELD is one of 'title', 'username', 'password', 'url', or a custom field.

type [-h] [--prog PROG] [--tabbed] [--username] [--xdotool] [name]
    Automatically type out the password as if the user had typed it on the keyboard, where PROG is a dmenu-like program for selecting an entry. PROG defaults to 'dmenu'. This is useful when you want to automatically fill a selected password field in any application. name is the name of the database to type from. If not given, type from all databases. Use the --tabbed option to type out the username then password, separated by a tab. Use the --username option to show entry username in parenthesis during selection. Use the --xdotool option to use xdotool instead of the Python keyboard library. Useful for handling unicode input. Note that this command is intended to be invoked via keyboard shortcut.

add [-h] [-w [LENGTH] | -a [LENGTH] | -s [LENGTH]] [--append STR] [--fields FIELD1,...] PATH
    Add a new entry/group to the database, where PATH is the full path to the entry or group. Use -w, -a, or -s to generate a correct horse battery staple (http://xkcd.com/936), alphanumeric, or alphanumeric + symbolic password, respectively. LENGTH defaults to 5 words for -w and 32 characters for -a and -s unless otherwise specified. Use --append to append STR to the end of the generated password to meet specific password requirements. Use --fields to specify a comma separated list of custom fields to prompt for during entry creation.

remove [-h] PATH
    Remove an entry/group from the database, where PATH is the full path to the entry or group.

edit [-h] [--field FIELD | --set FIELD VALUE | --remove FIELD] PATH
    Edit the contents of an entry or group, where PATH is the full path to the entry or group. You will be prompted to edit each field value. Use --field FIELD to edit only the specified field, where FIELD is one of title, username, password, url, or a custom field when editing entries. This option has no effect for groups. Use --set FIELD VALUE to set the value of a field, noninteractively for entries. Only name is supported for groups. Use --remove FIELD to remove an existing custom entry field. This option has no effect for groups.

move [-h] SRC_PATH DEST_PATH
    Move an entry/group to another path, where SRC_PATH and DEST_PATH are the full paths to the source and destination items. Providing two entry paths or two group paths will move and rename the entry or group.

list [-h] [--username] [PATH]
    List entries/groups in the database, where PATH is an optional path to a entry or group. Use the --username option to show entry username in addition to title.

grep [-h] [-i] [--field FIELD] PATTERN
    List entries with titles matching a regex pattern, where PATTERN is an XSLT style (https://www.xml.com/pub/a/2003/06/04/tr.html) regular expression. Use the --field FIELD option to search other string fields, where FIELD is one of title, username, password, url, or a custom field. Use the -i option to enable case insensitive searching.

kill [-h]
    Kill the background server.

init [-h]
    Create a new database. You will be prompted for the database password and whether or not to use a keyfile. See --database and --keyfile to initialize in a non-default location.

dump [-h]
    Pretty print database XML to console. Passwords will appear in plaintext.

OPTIONAL ARGS

-h, --help
    Print out a help message and exit. Use in conjunction with a command for command-specific help.

--debug
    Enable debug messages.

--database PATH
    Specify the path to the KeePass database when initializing, accessing or modifying the database. The config is ignored when this is given.

--keyfile PATH
    Specify the path to the keyfile when initializing, accessing or modifying the database. No effect if --database is not given.

--no-password
    Don't prompt for a password when accessing or modifying the database. No effect if --database is not given.

--no-cache
    Don't read from or write to cache while opening this database.

--cache-timeout
    Timeout to read from or write to cache while opening this database. No effect if --no-cache=True

--config PATH
    Specify path to config.

-v, --version
    Print out version information.

Files

~/.config/passhole.ini
    Default location of config. Specify multiple databases here or edit database options. See the config section for supported directives.

~/.local/passhole.kdbx
    Default location of KeePass database. Override with --database PATH

~/.local/passhole.key
    Default location KeePass key. Override with --keyfile PATH or in config.

Config

Located at ~/.config/passhole.ini by default. Can be overriden with the --config option. Each section in the config corresponds to a database. The supported options are:

database: /path/to/example.kdbx
    Required. The path to the kdbx file.

keyfile: /path/to/example.key
    Optional. Path to keyfile. If not given, assume database has no keyfile.

no-password: True
    Optional. Assume database has no password and don't prompt for it. If not given, the password will be loaded from cache or the user prompted.

no-cache: True
    Optional. Don't read from or write to cache when opening this database.

cache-timeout: 300
    Seconds to keep databases open in cache. Cache timeout is the same for all open databases and should be set in the first section in the config. The timeout timer resets with each passhole invocation. No effect if no-cache=True

default: True
    Optional. Set this database as default. When using multiple databases, entry or group paths with no @[Name] database prefix are assumed to refer to this database.

Multiple Databases

All commands support multiple databases. Prefix entry or group paths with @[Name]/, where [Name] is the database name given in the config. A path with no prefix is assumed to be the default database.

    # move an entry in the *test* database to the default database.
    $ ph mv @test/foobar_group/foobar_entry root_entry
    # list the test database
    $ ph ls @test/

More databases may be added using the init command or manually specified in the config:

    [test]
    # Use this database as the default
    # default: True
    # Path to database (required)
    database: /path/to/test.kdbx
    # Path to keyfile.  if absent, assume no keyfile
    keyfile: /path/to/test.key
    # Does the database have a password?
    # no-password: True
    # Path to password cache.  If absent, don't cache password.
    # Must be unique for each database
    cache: ~/.cache/test_cache

Python Scripts

The open_databases function is available for import for conveniently opening your database with password caching enabled. It returns an OrderedDict with database names as keys (as given in the config) and PyKeePass objects as values. The default database is the first element in this dictionary.

    from passhole.passhole import open_databases
    kp = list(open_databases().values()[0]

Examples

  add a new entry with manually created password

    $ ph add github
    Username: Evidlo
    Password:
    Confirm:
    URL: github.com

  add an entry with a generated alphanumeric password

    $ ph add neopets -a
    Username: Evidlo
    URL: neopets.com

  add a new group

    $ ph add social/

  add an entry to social/ with a 32 character password (alphanumeric + symbols)

    $ ph add social/facebook -s 32
    Username: evan@evanw.org
    URL: facebook.com

  add an entry to social/ with a correct-horse-battery-staple type password

    $ ph add social/twitter -w
    Username: evan@evanw.org
    URL: twitter.com

  list all entries

    $ ph list
    github
    neopets
    [social]
    ├── facebook
    └── twitter

  display contents of entry

    $ ph show social/twitter
    Title: twitter
    Username: Evidlo
    Password: inns.ambien.travelling.throw.force
    URL: twitter.com

  retrieve contents of specific field for use in scripts

    $ ph show social/twitter --field password
    inns.ambien.travelling.throw.force

AUTHORS
Evan Widloski.