diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7308a4b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,216 @@
+nag, a bash script for setting one-off or repeating alarms
+
+### Help
+
+<p>
+  <sup>
+    <a href="#installation">↑</a>
+  </sup>
+</p>
+
+<div align="center">
+  <a href="#nag-list"><code>list</code></a>&nbsp;·
+  <a href="#nag-at"><code>at</code></a>&nbsp;·
+  <a href="#nag-every"><code>every</code></a>&nbsp;·
+  <a href="#nag-stop"><code>stop</code></a>&nbsp;·
+  <a href="#nag-skip"><code>skip</code></a>&nbsp;·
+  <a href="#nag-check"><code>check</code></a>&nbsp;·
+  <a href="#nag-mute"><code>mute</code></a>&nbsp;·
+  <a href="#nag-unmute"><code>unmute</code></a>&nbsp;·
+  <a href="#nag-help"><code>help</code></a>&nbsp;·
+  <a href="#nag-version"><code>version</code></a>
+</div>
+
+#### `nag list`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag list
+
+Description:
+  List all alarms. This is the default when no subcommand is given.
+```
+
+#### `nag at`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag [at] <time> <message...>
+
+Description:
+  Create a one-shot alarm. The "at" is optional. If the first argument
+  doesn't match any other subcommand of nag, it'll fallback to "at".
+
+Examples:
+  nag 3pm take a break
+  nag at 3pm take a break
+  nag "tomorrow 9am" dentist appointment
+```
+
+#### `nag every`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag every <rules> <time> <message...>
+
+Description:
+  Create a repeating alarm. Rules are comma-separated and case-insensitive.
+
+Rules (and aliases):
+  hour    (h, hourly)    monday    (mon, mondays)
+  day     (d, daily)     tuesday   (tue, tuesdays)
+  week    (weekly)       wednesday (wed, wednesdays)
+  month   (monthly)      thursday  (thurs, thursdays)
+  year    (yearly)       friday    (fri, fridays)
+  weekday (weekdays)     saturday  (sat, saturdays)
+  weekend (weekends)     sunday    (sun, sundays)
+
+Examples:
+  nag every weekday 9am standup meeting
+  nag every tue,thu 3pm team sync
+  nag every year "December 25" Christmas
+```
+
+#### `nag stop`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag stop <id>
+
+Description:
+  Stop an alarm by ID.
+```
+
+#### `nag skip`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag skip <id>
+
+Description:
+  Skip the next occurrence of a repeating alarm (reschedule without firing).
+  For one-shot alarms, this deletes them.
+```
+
+#### `nag check`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag check
+
+Description:
+  Check for due alarms and fire them. Run automatically by a systemd
+  timer (every 15s) or cron (every 60s). Repeating alarms are
+  rescheduled. One-shot alarms are removed. Stale alarms older than
+  15 minutes are silently dropped or rescheduled without firing.
+```
+
+#### `nag mute`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag mute
+
+Description:
+  Mute alarm sounds. Notifications still fire, but no sound is played.
+```
+
+#### `nag unmute`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag unmute
+
+Description:
+  Unmute alarm sounds.
+```
+
+#### `nag help`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag help [<subcommand>]
+
+Description:
+  Display help information for nag or a specified subcommand.
+```
+
+#### `nag version`
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+```text
+Usage:
+  nag ( version | --version )
+
+Description:
+  Display the current program version.
+```
+
+### License
+
+<p>
+  <sup>
+    <a href="#help">↑</a>
+  </sup>
+</p>
+
+MIT - see [LICENSE](LICENSE).