diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6b25dc8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# ipaddrgen 👩‍💻
+### the funny ip address generator
+
+a small cli program written in go that generates random ip addresses and "does things" to them. (often very slowly)
+
+**Q:** *"why would you make this?"*
+
+**A:** I was very bored.
+
+# screenies 📸
+
+![ipaddrgen in action](screenshots/v1term.png)
+
+# install 📀
+
+### requirements:
+
+- go
+- that's about it
+
+### how:
+
+windows: `go build -o ./bin/ipaddrgen.exe`
+
+linux: `go build -o ./bin/ipaddrgen`
+
+mac: idk I've never built an executable for mac (should be about the same)
+
+---
+
+enjoy! ❤
\ No newline at end of file
diff --git a/screenshots/v1term.png b/screenshots/v1term.png
new file mode 100644
index 0000000..72f2fad
Binary files /dev/null and b/screenshots/v1term.png differ