From a853a212ab8babad61dd0a1b3ad5f7a54fe747d1 Mon Sep 17 00:00:00 2001
From: Lars Kellogg-Stedman <lars@redhat.com>
Date: Fri, 19 Oct 2018 16:26:58 -0400
Subject: [PATCH] Updated README to reflect recent changes

This updates the README to include instructions about installation
with `ansible-galaxy`, and adds several new examples.
---
 README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 87 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 07eedda..d9bac92 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,98 @@
 # ansible-modules-bitwarden
 
-Bitwarden integrations for Ansible
+Bitwarden integration for Ansible.
+
+## Installation
+
+The easiest way to install this lookup plugin is to use the
+`ansible-galaxy` command:
+
+    ansible-galaxy install git+https://github.com/c0sco/ansible-modules-bitwarden
+
+This will place the `ansible-modules-bitwarden` role into
+`$HOME/.ansible/roles`, where it will be available to all playbooks
+you run on your system.
 
 ## Lookup plugin
 
-Use `lookup()` with the `bitwarden` argument, followed by the items you want to retrieve. The default field is `password`, but any other field can be specified. If you need to specify the path to the Bitwarden CLI binary, use the `path` named argument. For example:
+To use this plugin, you will need to activate it by including the role
+in your play.  For example:
+
+    - hosts: localhost
+      roles:
+        - ansible-modules-bitwarden
+
+Use Ansible's `lookup()` function with the `bitwarden` argument,
+followed by the items you want to retrieve. The default field is
+`password`, but any other field can be specified using the `field`
+named argument. If you need to specify the path to the Bitwarden CLI
+binary, use the `path` named argument.
+
+## Examples
+
+### Get a single password
 
 ```yaml
-# Get username for Slashdot and Google
-- debug: msg="{{ lookup('bitwarden', 'Slashdot', 'Google', field='username', path='/not/in/my/path/bw') }}"
+# Get password for Google
+- debug:
+    msg: {{ lookup('bitwarden', 'Google') }}
 ```
 
-If you want to run the plugin directly for testing, you must first specify the field, then list the items to fetch.
+The above might result in:
 
-```bash
-lib/ansible/plugins/lookup/bitwarden.py username Google Slashdot
+```
+TASK [debug] *********************************************************
+ok: [localhost] => {
+    "msg": "mysecret"
+    }
+```
+
+### Get a single username
+
+```yaml
+# Get username for Google
+- debug:
+    msg: {{ lookup('bitwarden', 'Google', field='username' }}
+```
+
+The above might result in:
+
+```
+TASK [debug] *********************************************************
+ok: [localhost] => {
+    "msg": "alice"
+    }
+```
+
+### See all available fields
+
+```yaml
+# Get all available fields for an entry
+- debug:
+    msg: {{ lookup('bitwarden', 'Google', field='item' }}
+```
+
+The above might result in:
+
+```
+TASK [debug] *********************************************************
+ok: [localhost] => {
+    "msg": {
+        "favorite": false, 
+        "folderId": null, 
+        "id": "12345678-0123-4321-0000-a97001342c31", 
+        "login": {
+            "password": "mysecret", 
+            "passwordRevisionDate": null, 
+            "totp": null, 
+            "username": "alice"
+        }, 
+        "name": "Google", 
+        "notes": null, 
+        "object": "item", 
+        "organizationId": "87654321-1234-9876-0000-a96800ed2b47", 
+        "revisionDate": "2018-10-19T19:20:17.923Z", 
+        "type": 1
+    }
+}
 ```