#+TITLE: password-store-completion

A completion-based pass frontend inspired by [[https://github.com/carnager/rofi-pass][rofi-pass]]. Integrates with [[https://github.com/abo-abo/swiper][Ivy]] or [[https://github.com/oantolin/embark][Embark]].

The main purpose is typing passwords with =xdotool= (useful in [[https://github.com/emacs-exwm/exwm][EXWM]]).

Also take a look at Nicolas Petton's [[https://github.com/NicolasPetton/pass][pass]]. =password-store-completion= is designed as complementary to Nicolas' package.

* Installation
As the package isn't yet available anywhere but in this repository, you can clone the repository, add it to the load-path, and require the package. My preferred way is =use-package= with =straight=:

#+begin_src emacs-lisp
(use-package password-store-completion
  :straight (:host github :repo "SqrtMinusOne/password-store-completion"))
#+end_src

=xdotool= has to be available in =$PATH=.

For Ivy integration:
#+begin_src emacs-lisp
(require 'password-store-ivy)
#+end_src
Also be sure to load the main package before Ivy.

For Embark integration:
#+begin_src emacs-lisp
(require 'password-store-embark)
(password-store-embark-mode)
#+end_src

* Usage
Emacs' built-in [[https://www.gnu.org/software/emacs/manual/html_node/auth/The-Unix-password-store.html][password store]] integration has to be set up.

For Ivy integration, the command is =M-x password-store-ivy=, which invokes Ivy to select an entry from the pass database. Available commands in the selection buffer:
- =M-a=: Perform autotype
- =M-p=: Type password
- =M-u=: Type username
- =M-U=: Type URL
- =M-f=: Select a field to type

For other completion frameworks, run =M-x password-store-completion=. If Embark integration is enabled, the same actions are added.

* Customization
The following parameters control delays:
- =password-store-completion-initial-wait= controls the initial delay before starting to type a sequence (in milliseconds)
- =password-store-completion-delay= controls the delay between typing characters (in milliseconds)

=password-store-completion-sequences= determines the steps of sequences. It is an alist; the keys correspond to the default sequences:
- =autotype=
- =password=
- =username=
- =url=

The values are lists of the following elements:
- =wait=: Wait for =password-store-completion-initial-wait= milliseconds
- =(wait <milliseconds>)=: Wait for =<milliseconds>=
- =(key <key>)=: Type =<key>=
- =(field <field>)=: Type =<field>= of entry

The default value is as follows:
#+begin_src emacs-lisp
'((autotype . (wait
               (field . "username")
               (key . "Tab")
               (field . secret)
               (key . "Return")))
  (password . (wait (field . secret)))
  (username . (wait (field . "username")))
  (url . (wait (field . "url"))))
#+end_src

Sequences can also be overridden in a particular entry with a field called =sequence-<name>=, where =<name>= is a key of =password-store-completion-sequences=.

For example, to press =Tab= twice in the =autotype= sequence:
#+begin_example
<pass>
username: thexcloud@gmail.com
url: <url>
sequence-autotype: (wait (field . "username") (key . "Tab") (key . "Tab") (field . secret) (key . "Return"))
#+end_example

Or, create a custom sequence:
#+begin_example
<pass>
username: thexcloud@gmail.com
url: <url>
sequence-doubletab: (wait (field . "username") (key . "Tab") (key . "Tab") (field . secret) (key . "Return"))
#+end_example

Custom sequences can be run in the field selection interface (=M-f= in Ivy, =M-x embark-act f= in Embark).