diff --git a/README.md b/README.md
index e69de29..59b025b 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,26 @@
+# bookshelf-generator
+
+This is a python script for two tasks:
+1. downloading the contents of a bookwyrm list into a yaml file, along with a directory containing all the cover images for the listed books
+2. using the yaml file and image directory from the previous step to generate a static HTML file using a jinja template file of your choice
+
+
+Here is an example, of using the both parts of the script, with the list https://bookwyrm.social/list/2634/s/calvin-and-hobbes
+```
+# download the bookwyrm list at https://bookwyrm.social/list/2634/s/calvin-and-hobbes and save the contents into a yaml as well as all the cover images into a folder at calvin-and-hobbes
+python3 main.py bookwyrm-download --list-url="https://bookwyrm.social/list/2634/s/calvin-and-hobbes" --output-dir="calvin-and-hobbes"
+# from the yaml and directory of images downloaded in the previous step, generate a static html page using the template in templates/bookshelf.html
+python3 main.py generate-html --yaml-path="calvin-and-hobbes/books.yaml" --images-dir="calvin-and-hobbes" --template="templates/calvin-and-hobbes.html" --output-path="output/calvin-and-hobbes"
+```
+
+I used required named arguments for this script, for clarity of what arguments were being passed. 
+
+I divided the script into two subcommands, bookwyrm-download and generate-html, so that they could potentially be used independently. 
+
+If in the future the bookwyrm schema changes and I don't feel like updating the script,
+I can switch to just manually editing yaml files and creating image directories,
+and continue using the generate-html script. 
+
+Example template files are in the templates folder and are made using jinja. You can modify these or make your own. 
+
+https://books.commoninternet.net is an example website generated with this script from three bookwyrm lists.