diff --git a/README.md b/README.md
index 3ed30c9..fd83192 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,39 @@
 > **WARNING**: still in prototype stage...
 
 Automate your mass typo updates.
+
+## CLI
+
+- **--reset**: run `git-checkout` on all of your glob matches and exit
+- **--validate**: ensure your `Migration` sub-class is valid
+- **--yaml**: tell `tyop` that it should try to load the YAML with [ruamel.yaml](https://yaml.readthedocs.io/en/latest/)
+- **--debug**: enable debug logging
+
+## Logic
+
+- Match all files specified by the `GLOB` pattern and apply the following
+    - Check out main/master, `git-pull` and `git-checkout` for clean branch
+    - Feed matched file contents into `Migration` sub-class and show the diff
+    - Show a few diffs to make sure things are running smoothly and then apply to all matches
+    - Iterate through all matches and `git-commit`/`git-push` changes (Use `s` to skip changes)
+
+## Example migration
+
+```python
+from tyop import Migration
+
+
+class InternalTrueMigration(Migration):
+    GLOB = "~/.abra/apps/**/compose*.yml"
+
+    def migrate(self, compose):
+        try:
+            if "internal" in compose["networks"]:
+                compose["networks"]["internal"] = {"internal": True}
+            return compose
+        except Exception:
+            return compose
+
+
+InternalTrueMigration()
+```