diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c7d7db5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,19 @@
+# mailalias - simple alias / catch-all management tool for iRedMail (MySQL/MariaDB)
+
+## Alias model used:
+- alias table contains alias addresses
+- forwardings contains destination rows for aliases with is_list=1
+- catch-all entries are stored in forwardings where address == domain
+
+### Examples:
+```sh
+mailalias alias-add contact@charlesdanesi.com charles@charlesdanesi.com
+mailalias alias-remove admin@beyemir.com charles@beyemir.com
+mailalias alias-lookup admin@charlesdanesi.com
+mailalias alias-list
+mailalias alias-list-user charles@danesisolutions.com
+
+mailalias catchall-add beyemir.com charles@beyemir.com
+mailalias catchall-remove beyemir.com charles@beyemir.com
+mailalias catchall-list
+```