diff --git a/README.md b/README.md
index 3a606ed..5ab2722 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,49 @@
 # hellpipe
 
-wip: generate python scripts from (s)hell pipelines
\ No newline at end of file
+wip: generate python scripts from (s)hell pipelines
+
+Intended to be used with a shell plugin to make those oneliners that get out of hand more manageable.
+
+## Example
+
+`curl "https://httpbin.org/get?test=123" | jq ".headers|keys[]" -r | xargs -L 1 echo`
+
+```python
+import requests
+import subprocess
+import sys
+import shlex
+
+# generated with hellpipe
+
+def main():
+
+    params = {"test": ["123"]}
+    res = requests.get("https://httpbin.org/get", params=params).text
+
+    proc = subprocess.Popen(
+        ["jq", ".headers|keys[]", "-r"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=sys.stderr,
+    )
+    (stdout, _) = proc.communicate(res.encode("utf-8"))
+    out_jq = stdout.decode("utf-8")
+
+    for i in shlex.split(out_jq, posix=True):
+        print(i)  # TODO
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Currently Supported Mappings
+
+ - [x] curl -> requests (very basic)
+ - [ ] xargs (only prints)
+ - [x] shell commands (no stderr capture)
+ - [ ] jq via bindings
+ - [ ] head/tail
+ - [ ] sort
+ - [ ] basic shell loops