Update README

2 files changed, 82 insertions, 53 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..183521c
--- /dev/null
+++ b/README
@@ -0,0 +1,82 @@
+awscli-plugin-passtotp
+======================
+
+This plugin enables aws-cli to directly talk to pass to acquire an
+OATH-TOTP code using the pass-otp extension.
+
+Dependencies
+------------
+
+* pass
+* pass-otp
+* python
+* aws-cli
+
+Installation
+------------
+
+Building and installing awscli-plugin-passtotp requires a working
+Python 3 installation.
+
+a) To install it from a cloned repository:
+
+    $ python3 -m pip install .
+
+b) You can also install it directly from PyPi like this:
+
+    $ python3 -m pip install awscli-plugin-passtotp
+
+Enabling the plugin
+-------------------
+
+A new entry to the plugins section in your config (~/.aws/config)
+must be added to enable the plugin:
+
+    [plugins]
+    passtotp = awscli_plugin_passtotp
+
+If using aws-cli version 2 you must specify the path to where the
+package was installed. You can use the following command to find
+the right location:
+
+    $ pip show awscli-plugin-passtotp | grep Location:
+
+And then add the following to your config (~/.aws/config):
+
+    [plugins]
+    cli_legacy_plugin_path = /usr/local/lib/python3.10/dist-packages
+    passtotp = awscli_plugin_passtotp
+
+AWS CLI configuration
+---------------------
+
+Specify a path to a file in your passord-store in the profiles where
+you want to use the plugin.
+
+    [profile bar]
+    mfa_path = foo/aws/bar
+    ...
+
+You can ensure you have a working pass-otp entry by running:
+
+    $ pass otp foo/aws/bar
+
+Where 'foo/aws/bar' is an entry added by 'pass otp', eg:
+
+    $ pass otp insert foo/aws/bar
+
+Usage
+-----
+
+Just use the aws command with a custom role and the plugin will
+obtain the TOTP token from pass:
+
+    $ aws s3 ls --profile myprofile
+    2013-07-11 17:08:50 mybucket
+    2013-07-24 14:55:44 mybucket2
+
+Acknowledgements
+----------------
+
+This plugin was primarily based off the work of tommie-lie in
+https://github.com/tommie-lie/awscli-plugin-yubikeytotp
diff --git a/README.md b/README.md
deleted file mode 100644
index 358180f..0000000
--- a/README.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# AWS CLI MFA with pass-otp made easy
-
-This plugin enables aws-cli to directly talk to [pass](https://www.passwordstore.org/)
-to acquire an OATH-TOTP code using the [pass-otp](https://github.com/tadfisher/pass-otp) extension.
-
-## Installation
-
-`awscli-plugin-passtotp` can be installed from PyPI:
-```sh
-$ pip install awscli-plugin-passtotp
-```
-
-It's also possible to install it just for your user in case you don't have
-permission to install packages system-wide:
-```sh
-$ pip install --user awscli-plugin-passtotp
-```
-
-### Configure AWS CLI
-
-To enable the plugin, add this to your `~/.aws/config`:
-```ini
-[plugins]
-# If using aws-cli v2 you must specify the path to where the package was installed.
-# Use `pip show awscli-plugin-passtotp | grep Location:` to find the right location.
-cli_legacy_plugin_path = /foo/bar/lib/python3.9/site-packages/
-
-passtotp = awscli_plugin_passtotp
-```
-
-Also make sure to specify a path to a file in your password-store in the profiles managed by pass:
-```ini
-[profile myprofile]
-role_arn = arn:aws:iam::...
-mfa_serial = arn:aws:iam::...
-mfa_path = foo/aws/bar
-...
-```
-
-## Usage
-
-Just use the `aws` command with a custom role and the plugin will do the rest:
-
-```sh
-$ aws s3 ls --profile myprofile
-2013-07-11 17:08:50 mybucket
-2013-07-24 14:55:44 mybucket2
-```
-
----
-
-## Acknowledgements
-* Thanks to [@tommie-lie](https://github.com/tommie-lie) for [awscli-plugin-yubikeytotp](https://github.com/tommie-lie/awscli-plugin-yubikeytotp)