diff --git a/README.md b/README.md
index 258acd4..cc62249 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,28 @@
-# sotp: sops otp
+# SOTP: Sops OTP
 
-small utility to store aws totp secrets into sops encrypted files and generate totp on the command line.
+Small utility to store AWS TOTP secrets into Sops encrypted files and generate OTP on the command line.
+
+[![CircleCI](https://circleci.com/gh/mozilla/sotp.svg?style=svg)](https://circleci.com/gh/mozilla/sotp)
 
 usage:
 
 ```
 $ sotp test1
 current one-time password is: 693190
-```
\ No newline at end of file
+```
+
+Sotp reads it's configuration from `config.yaml` in the local directory.
+The config must be a valid Sops encrypted YAML file with the syntax:
+
+```yaml
+accounts:
+    - name: test1
+      totpsecret: YAGQP5IP77OO3HMPS3D2KPMSNLNDIB7EO22EGAN3JEGE3DAR37Z2U5YDGKGN44VA
+    - name: test2
+      totpsecret: xyzabcd....
+```
+
+* `name` is just a reference name that you'll use when invoking Sotp
+* `totpsecret` is a the secret seed you get from the `Adding a virtual MFA` screen in the AWS IAM console of a given user
+
+![aws_mfa_screen](./docs/aws_vmfa.png)
\ No newline at end of file
diff --git a/docs/aws_vmfa.png b/docs/aws_vmfa.png
new file mode 100644
index 0000000..924253b
Binary files /dev/null and b/docs/aws_vmfa.png differ