108 lines
3.8 KiB
Org Mode
108 lines
3.8 KiB
Org Mode
#+title: bitwarden.el
|
||
#+author: Lucien Cartier-Tilet
|
||
#+email: lucien@phundrak.com
|
||
|
||
* Introduction
|
||
Bitwarden.el is a Bitwarden porcelain for Emacs. It aims to be a
|
||
complete text-based interface for the [[https://github.com/bitwarden/cli][Bitwarden CLI]].
|
||
|
||
Most of its public function are transient functions from the
|
||
transient library to provide the user an easy-to-use interface with
|
||
most of its options exposed.
|
||
|
||
This package is still very much a work in progress. Use at your own
|
||
risks.
|
||
|
||
* Table of Contents :TOC_2_gh:
|
||
- [[#introduction][Introduction]]
|
||
- [[#installation][Installation]]
|
||
- [[#notes][Notes]]
|
||
- [[#login][Login]]
|
||
- [[#customizing][Customizing]]
|
||
- [[#contributing][Contributing]]
|
||
- [[#license][License]]
|
||
|
||
* Installation
|
||
A couple of options are available for installing bitwarden.el.
|
||
|
||
The first one is to clone the repository in your ~load-path~ and add the
|
||
following to your ~.emacs~ or your ~init.el~:
|
||
#+begin_src emacs-lisp
|
||
(require 'bitwarden.el)
|
||
#+end_src
|
||
|
||
In my case, I prefer using ~use-package~ with ~straight~:
|
||
#+begin_src emacs-lisp
|
||
(use-package bitwarden
|
||
:ensure t
|
||
:defer t
|
||
:straight (bitwarden :type git
|
||
:host nil
|
||
:repo "https://labs.phundrak.com/phundrak/bitwarden.el"))
|
||
#+end_src
|
||
|
||
I personally also added ~:build t~ in the straight recipe to ensure
|
||
Emacs compiles my package, both to ~.elc~ and ~.eln~ files (I am on Emacs
|
||
28.0, ~feature/native-comp~ got merged into ~master~!)
|
||
|
||
There is probably a similar way to install it with pure ~straight.el~ or
|
||
~quelpa~, but I’m not knowledgable enough for that, feel free to create
|
||
a PR to add some more installation instructions!
|
||
|
||
There is currently no plans of making this package available on MELPA
|
||
or non-gnu elpa.
|
||
|
||
* Notes
|
||
** Login
|
||
Loging in with the ~--apikey~ option is not supported due to its
|
||
interactive nature.
|
||
|
||
Bitwarden allows three different sources for your password:
|
||
- a plain password as an argument following the username
|
||
- an environment variable containing the password
|
||
- a file containing the password
|
||
Bitwarden.el allows a fourth option: the authinfo file on computer. To
|
||
use this option, simply add the following line in your ~.authinfo~ or
|
||
~.authinfo.gpg~ file:
|
||
#+begin_src text
|
||
machine bitwarden.example.com login yourusername password yourpassword
|
||
#+end_src
|
||
|
||
Of course, you will have to replace ~bitwarden.example.com~ with the
|
||
actual server, ~yourusername~ with your actual username, and
|
||
~yourpassword~ with your actual password. If you do not set your
|
||
username or your password in bitwarden.el, the package will look for
|
||
them in your auth source file on login. Bitwarden.el retrieves the
|
||
server name from the command
|
||
#+begin_src bash
|
||
$ bw config server
|
||
#+end_src
|
||
and it strips the result from any ~http://~ or ~https://~ prefix. For
|
||
instance, if the command returns ~https://example.com/bitwarden~,
|
||
bitwarden.el will look for ~example.com/bitwarden~ in your authinfo
|
||
file.
|
||
|
||
* Customizing
|
||
Bitwarden.el has a couple of customizable variables you can find in
|
||
the ~bitwarden~ group when executing ~M-x customize-group~. Here is a
|
||
quick description of these variables:
|
||
- ~bitwarden-cli-executable~ :: Your Bitwarden CLI executable. Set this
|
||
variable if Emacs doesn’t find ~bw~ in your ~$PATH~ or if ~bw~ does not
|
||
refer to your Bitwarden CLI.
|
||
|
||
Default value: ~bw~
|
||
- ~bitwarden-default-cli-arguments~ :: A list of the default arguments
|
||
to pass to Bitwarden CLI. By default, only the package only passes ~--nointeraction~ in order to inhibit any attempt from the CLI to
|
||
launch anything interactive --- it should be taken care of by the
|
||
package itself.
|
||
|
||
Default value: ~'("--nointeraction")~
|
||
|
||
* Contributing
|
||
See [[file:CONTRIBUTING.org]].
|
||
|
||
* License
|
||
~bitwarden.el~ is available under the GNU GPL-3.0 license. You can
|
||
find the full text in [[file:LICENSE.md][LICENSE.md]].
|