bitwarden.el/README.org

108 lines
3.8 KiB
Org Mode
Raw Normal View History

2022-02-13 13:12:29 +00:00
#+title: bitwarden.el
2022-02-13 12:52:47 +00:00
#+author: Lucien Cartier-Tilet
#+email: lucien@phundrak.com
* Introduction
2022-02-13 13:12:29 +00:00
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.
2022-03-02 17:04:46 +00:00
This package is still very much a work in progress. Use at your own
risks.
2022-02-13 12:52:47 +00:00
* Table of Contents :TOC_2_gh:
- [[#introduction][Introduction]]
- [[#installation][Installation]]
2022-02-13 13:12:29 +00:00
- [[#notes][Notes]]
- [[#login][Login]]
2022-02-13 12:52:47 +00:00
- [[#customizing][Customizing]]
- [[#contributing][Contributing]]
- [[#license][License]]
* Installation
2022-02-13 13:12:29 +00:00
A couple of options are available for installing bitwarden.el.
2022-02-13 12:52:47 +00:00
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
2022-03-02 17:04:46 +00:00
(require 'bitwarden.el)
2022-02-13 12:52:47 +00:00
#+end_src
In my case, I prefer using ~use-package~ with ~straight~:
#+begin_src emacs-lisp
2022-03-02 17:04:46 +00:00
(use-package bitwarden
:ensure t
:defer t
:straight (bitwarden :type git
:host nil
:repo "https://labs.phundrak.com/phundrak/bitwarden.el"))
2022-02-13 12:52:47 +00:00
#+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 Im 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.
2022-02-13 13:12:29 +00:00
* 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.
2022-02-13 12:52:47 +00:00
* Customizing
2022-02-13 13:12:29 +00:00
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 doesnt 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")~
2022-02-13 12:52:47 +00:00
* Contributing
See [[file:CONTRIBUTING.org]].
* License
2022-02-13 13:12:29 +00:00
~bitwarden.el~ is available under the GNU GPL-3.0 license. You can
2022-02-13 12:52:47 +00:00
find the full text in [[file:LICENSE.md][LICENSE.md]].