diff --git a/README.md b/README.md index 2ff3633..38b3c31 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,104 @@ +password store logo + ## pass-tessen -A [pass](https://www.passwordstore.org/) extension that uses [fzf](https://github.com/junegunn/fzf) -to select and copy password store data. +`pass-tessen` is a [password store][1] extension that uses a fuzzy data selection menu to copy +password store data while using a terminal. `pass-tessen` can open URLs in a web browser of your +choice, generate OTPs using [pass-otp][2], and copy all [valid key-value pair data][3] in a password +store file. The fuzzy data selection menu can be either [fzf][4], [skim][5], or [fzy][6]. + +If you want to autotype and copy password store and [gopass][21] data on Wayland wlroots compositors +like [sway][7], check out [tessen][8]. If you're using Xorg/X11 window managers, check out +[rofi-pass][9]. + +## Why use `pass-tessen`? + +- unlike [pass-clip][10], `pass-tessen` can copy all valid key-value pair data in a password store + file + + For example, if you have something like + + ``` + $ pass show mybank/username + correct horse battery staple + url: https://mybank.com + credit card number: 1111 1111 1111 1111 + otpauth://totp/ACME%20Co:john@example.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30 + ``` + + `pass-tessen` can copy the value of `credit card number` key + +- `pass-tessen` can generate and copy OTPs if [pass-otp][2] is installed + +- `pass-tessen` can open URLs using [xdg-open][11] or any other web browser of your choice + +- `pass-tessen` can show a preview of your password store data before you select it -If you want to autotype and copy password-store data, similar to how -[rofi-pass](https://github.com/carnager/rofi-pass) works, check out -[tessen](https://github.com/ayushnix/tessen). + + + pass-tessen preview showcase + -`pass-tessen` will automatically use the following environment variables if they're set or assume -reasonable defaults if not. +- focuses on doing one thing well, copying password store data while using a terminal -- `PASSWORD_STORE_DIR` (the default location of your password store) -- `PASSWORD_STORE_CLIP_TIME` (the amount of time for which password-store data stays on the - clipboard) +- `pass-tessen` doesn't use any external dependencies unless absolutely necessary + + As a result, `pass-tessen` doesn't depend on commonly used utilities like coreutils, sed, awk, and + find (although password store needs them). + +- the code is linted using [shellcheck][12] and formatted using [shfmt][13] + +- focuses on minimalism and security (please let me know if you have any suggestions for + improvement) ## Installation -Before installing `pass-tessen`, make sure you've added the following line in `~/.bash_profile` or -an equivalent file and have logged out and logged back in. +Before installing `pass-tessen`, make sure that the environment variable +`PASSWORD_STORE_ENABLE_EXTENSIONS` is set to `true`. This can be confirmed by executing, + +``` +env | grep PASSWORD_STORE_ENABLE_EXTENSIONS +``` + +If there's no output, add the following line in `~/.bash_profile` assuming you're using bash and +re-login. ``` export PASSWORD_STORE_ENABLE_EXTENSIONS=true ``` -Password Store extensions will not work if this environment variable isn't set. +If this environment variable isn't set, password store extensions will not work. For more details, +please read the man page of `PASS(1)`. ### Dependencies -- [pass](https://git.zx2c4.com/password-store/) -- [fzf](https://github.com/junegunn/fzf) -- [xclip](https://github.com/astrand/xclip) (if you're using X11/Xorg) -- [wl-clipboard](https://github.com/bugaevc/wl-clipboard) or - [wl-clipboard-rs](https://github.com/YaLTeR/wl-clipboard-rs) (if you're using Wayland) +- [pass][1] +- at least one fuzzy data selection backend is needed - either [fzf][4], [skim][5], or [fzy][6] +- at least one copy paste program is needed - either [wl-clipboard][15] if you're using a Wayland + compositor or [xclip][14] if you're using Xorg/X11 +- [xdg-utils][11] (optional, if you want to open URLs using `xdg-open`) +- [pass-otp][2] (optional, if you want to generate and copy TOTP/HOTP) ### Arch Linux -`pass-tessen` is available in the [Arch User -Repository](https://aur.archlinux.org/packages/pass-tessen/). +`pass-tessen` is available in the [Arch User Repository][17]. ### Git Release ``` -git clone https://github.com/ayushnix/pass-tessen.git +git clone https://git.sr.ht/~ayushnix/pass-tessen cd pass-tessen sudo make install ``` -You can also do `doas make install` if you're using [doas](https://github.com/Duncaen/OpenDoas), -which you probably should. +You can also do `doas make install` if you're using [doas][18] on Linux, which you probably should. ### Stable Release ``` -wget https://github.com/ayushnix/pass-tessen/releases/download/v1.5.3/pass-tessen-1.5.3.tar.gz -tar xvzf pass-tessen-1.5.3.tar.gz -cd pass-tessen-1.5.3 +wget https://git.sr.ht/~ayushnix/pass-tessen/archive/v2.0.0.tar.gz +tar xvzf pass-tessen-2.0.0.tar.gz +cd pass-tessen-2.0.0 sudo make install ``` @@ -63,58 +107,38 @@ or, you know, `doas make install`. ## Usage ``` -Usage: pass tessen [-p|--preview] [-h|--help] [-v|--version] - -p, --preview: show preview of password data - -h, --help: print this help menu - -v, --version: print the version of pass tessen +usage: pass tessen [-p|--preview] [-f|--fuzzy fuzzy_backend_program] + [-u|--userkey custom_username_key] + [-U|--urlkey custom_url_key] + [-w|--web-browser custom_web_browser] [-h|--help] + [-v|--version] + +pass tessen find a fuzzy selection program and show pass data +pass tessen -p show preview while selecting a pass file +pass tessen -p -f sk use skim as fuzzy backend and show preview +pass tessen -f fzy use fzy as fuzzy backend; doesn't support preview +pass tessen -u username set 'username' as the custom username key +pass tessen -U URL set 'URL' as the custom URL key +pass tessen -w qutebrowser use qutebrowser to open URLs +pass tessen -h show this help menu +pass tessen -v show the version of pass tessen ``` -## Why should I use this instead of [pass-clip](https://github.com/ibizaman/pass-clip)? - -- pass-tessen can copy other key-value pair data, not just passwords - - For example, if you have something like - - ``` - $ pass show mybank/username - correct horse battery staple - url: https://mybank.com - credit card number: 1111 1111 1111 1111 - ``` - - pass tessen can copy your `username`, `url`, and `credit card number` as well - -- pass-tessen can show a preview of your password-store data before you select it - - just use `pass tessen -p` to see a preview of your password store data before you make a selection -- focuses on doing one thing well, copying password store data as conveniently and quickly as - possible while using a terminal -- you don't need `sed`, `find`, GNU coreutils, or anything else besides what's mentioned above to - run pass-tessen (although `pass` needs all of those binaries) -- the code is linted using [shellcheck](https://github.com/koalaman/shellcheck) and formatted using - [shfmt](https://github.com/mvdan/sh) -- focuses on minimalism and security (please let me know if you have any suggestions for - improvement) - ## Assumptions -`pass-tessen` works under several assumptions and tries to fail gracefully if they are not met. -Please report any unexpected behavior. - -The data organization format is assumed to be the same as mentioned on this -[page](https://www.passwordstore.org/). If valid key-value pairs aren't found, `pass-tessen` will -not show them. - -It is assumed that the name of the file itself is the username. For example, if you have a file -`bank/mybankusername.gpg` in your password store, the assumed default username is `mybankusername`. -However, if a valid username key value pair is present inside the file, `pass-tessen` will show them -for selection as well. +`pass-tessen` assumes that the data organization format in a password store file is the same as +mentioned on the [password store website][3]. If a key is not detected, please raise a ticket on a +git forge website of your choice where `pass-tessen` is hosted. -If there are multiple non-unique keys, the value of the last key will be considered. +The `password` key is reserved in a case-insensitive manner to avoid confusion. The custom username +and URL keys are also checked in a case-insensitive manner and the first unique key is selected. If +a custom username key is not mentioned, `user` is assumed. If a custom URL key is not mentioned, +`url` is assumed. If a username key is not found, the basename of the selected password store +(without the `.gpg` extension) is considered as the username. ## What does `tessen` mean? -[Here](https://en.wikipedia.org/wiki/Japanese_war_fan) you go. +[Here you go.][20] ## Why did you choose this weird name? @@ -124,4 +148,26 @@ of Japanese hand fans. I guess I was thinking of some anime while coming up with ## Contributions -Please see [this](https://github.com/ayushnix/pass-tessen/blob/master/CONTRIBUTING.md) file. +Please see the [CONTRIBUTING.md file][19]. + +[1]: https://www.passwordstore.org/ +[2]: https://github.com/tadfisher/pass-otp +[3]: https://www.passwordstore.org/#organization +[4]: https://github.com/junegunn/fzf +[5]: https://github.com/lotabout/skim +[6]: https://github.com/jhawthorn/fzy +[7]: https://swaywm.org/ +[8]: https://git.sr.ht/~ayushnix/tessen +[9]: https://github.com/carnager/rofi-pass +[10]: https://github.com/ibizaman/pass-clip +[11]: https://www.freedesktop.org/wiki/Software/xdg-utils/ +[12]: https://github.com/koalaman/shellcheck +[13]: https://github.com/mvdan/sh +[14]: https://github.com/astrand/xclip +[15]: https://github.com/bugaevc/wl-clipboard +[16]: https://github.com/YaLTeR/wl-clipboard-rs +[17]: https://aur.archlinux.org/packages/pass-tessen/ +[18]: https://github.com/Duncaen/OpenDoas +[19]: https://git.sr.ht/~ayushnix/pass-tessen/tree/master/item/CONTRIBUTING.md +[20]: https://en.wikipedia.org/wiki/Japanese_war_fan +[21]: https://github.com/gopasspw/gopass