NAME

       impass - Simple and secure password management and retrieval system

SYNOPSIS

       impass <command> [<args>...]

DESCRIPTION

       The  password  database  is  stored as a single json object, OpenPGP encrypted and signed, and written to
       local disk (see IMPASS_DB). The file is created upon addition of the first entry.  Database  entries  are
       keyed  by  'context'.  During  retrieval  of  passwords  the  database is decrypted and read into memory.
       Contexts are searched by sub-string match.

       Contexts can be any string. If a context string is not specified on the command line it can  be  provided
       at  a  prompt, which features tab completion for contexts already in the database. One may also specify a
       context of '-' to read the context from stdin, or ':' to force a prompt.

       Passwords are auto-generated by default with 18 bytes of entropy. The number of octets can  be  specified
       with the IMPASS_PASSWORD environment variable or via the 'pwspec' optional argument to relevant commands.
       The  length  of  the actually generated password will sometimes be longer than the specified bytes due to
       base64 encoding. If pwspec is ':' the user will be prompted for the password.

COMMANDS

       add [-h] [context] [pwspec]
              Add new entry. If the context already exists in the database an error will be thrown.

       replace [-h] [context] [pwspec]
              Replace password for entry. If the context does not already exist in the database an error will be
              thrown.

       update [-h] [old_context] [new_context]
              Update context for existing entry, keeping password the same.  Special context value  of  '-'  can
              only be provided to the old context.

       dump [-h] [string]
              Dump  password  database  to  stdout  as  json.  If a string is provide only entries whose context
              contains the string will be dumped. Otherwise all entries are  returned.  Passwords  will  not  be
              displayed unless IMPASS_DUMP_PASSWORDS is set.

       get [-h] [context]
              Print password matching context to stdout.

       gui [-h] [string]
              Launch  minimal GUI. Good for X11 or Wayland-based window manager integration. Upon invocation the
              user will be prompted to decrypt the database, after which  a  graphical  search  prompt  will  be
              presented. If an additional string is provided, it will be added as the initial search string. All
              matching  results  for  the  query  will  be presented to the user. When a result is selected, the
              password will be retrieved according to the method specified by  IMPASS_XPASTE.  If  no  match  is
              found,  the user has the opportunity to generate and store a new password, which is then delivered
              via IMPASS_XPASTE. Note: contexts that have leading or  trailing  whitespace  are  not  accessible
              through the GUI.

       remove [-h] [context]
              Remove entry. If the context does not already exist in the database an error will be thrown.

       help [-h]
              Full usage or command help (also '-h' after command).

       version [-h]
              Print version.

SIGNATURES

       During  decryption,  OpenPGP signatures on the db file are checked for validity. If any of them are found
       to not be valid, a warning message will be written to stderr.

ENVIRONMENT

       IMPASS_DB
              Path to impass database file. Default: ~/.impass/db

       IMPASS_KEYFILE
              File containing OpenPGP key ID of database encryption recipient. Default: ~/.impass/keyid

       IMPASS_KEYID
              OpenPGP key ID of database encryption recipient. This overrides IMPASS_KEYFILE if set.

       IMPASS_PASSWORD
              See Passwords above.

       IMPASS_DUMP_PASSWORDS
              Include passwords in dump when set.

       IMPASS_XPASTE
              Method for password retrieval from GUI. Options are: 'xdo', which attempts to  type  the  password
              into  the  window that had focus on launch, 'xclip' which inserts the password in the X clipboard,
              and 'sway', which types the password into the focused wayland container.  Default:  xdo  or  sway,
              detected automatically.

AUTHOR

       Jameson Graef Rollins <jrollins@finestructure.net> Daniel Kahn Gillmor <dkg@fifthhorseman.net>

impass                                           08 January 2025                                       impass(1)