Start of bitwarden.el

README.org

@@ -1,34 +1,42 @@
-#+title: TEMPLATE-NAME
+#+title: bitwarden.el
 #+author: Lucien Cartier-Tilet
 #+email: lucien@phundrak.com
 
 * Introduction
-Describe briefly what the package is, what it does, and who it is for.
+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.
+
 
 * 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 ~TEMPLATE-NAME~.
+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 'TEMPLATE-NAME)
+  (require 'bitwarden.el)
 #+end_src
 
 In my case, I prefer using ~use-package~ with ~straight~:
 #+begin_src emacs-lisp
-  (use-package TEMPLATE-NAME
+  (use-package bitwarden
     :ensure t
     :defer t
-    :straight (TEMPLATE-NAME :type git
+    :straight (bitwarden :type git
                              :host nil
-                             :repo "https://labs.phundrak.com/phundrak/TEMPLATE-NAME"))
+                             :repo "https://labs.phundrak.com/phundrak/bitwarden.el"))
 #+end_src
 
 I personally also added ~:build t~ in the straight recipe to ensure
@@ -42,14 +50,56 @@ 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
-Indicate the various customization options available, e.g. variables
-and faces. For each one of them, give a brief description and their
-default value.
+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
-~TEMPLATE-NAME.el~ is available under the GNU GPL-3.0 license. You can
+~bitwarden.el~ is available under the GNU GPL-3.0 license. You can
 find the full text in [[file:LICENSE.md][LICENSE.md]].