diff --git a/README.md b/README.md
index 6057b75..a31c3d2 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,50 @@
 # mmcli
 
-## Install
-With pip or pipx.
+Interact with Mattermost on the command line and in scripts
+
+## Usage
+```
+mmcli [-h] [-i] [--format {tsv,json}] [--server SERVER] action [subarguments..]
+
+options:
+  -h, --help            show this help message and exit
+  -i, --ids             use IDs instead of names
+  --format {tsv,json}   output format; only json has all fields; default: json
+  --server SERVER       e.g.: mattermost.example.org; example.org/mattermost; envvar: MM_SERVER
+
+actions:
+    login               retrieve an access token
+    cat                 list messages in channel
+    tail                list newest messages in channel
+    ls                  list channels
+    send                send message(s)
+    rm                  delete message(s)
+    edit                edit message(s)
+    addreaction         add emoji reaction to a message
+    removereaction      remove emoji reaction from a message
+    listcustomemoji     list all custom emoji on the server
+    status              update user status
+    customstatus        update custom user status (emoji and message)
+    lastread            last read message in channel; will be null if all messages are read
+
+For further help, use `mmcli <action> -h`.
+```
+
+You can request an access token with `mmcli login`, then provide it to future incantations of mmcli by setting the environment variable MM_ACCESSTOKEN.
+
+Where a "URL name" is required, "id:" plus an ID can also be used instead. So these could both be valid:
+- town-square
+- id:123abc456def789ghi012jkl34
+
+Hint: JSON output can be filtered with jq(1).
+
+## Installation
+With pip or pipx:
+
+```
+git clone https://git.zeus.gent/midgard/mmcli
+pipx install ./mmcli
+```
 
 ## Development
 To create a virtualenv and install the dependencies in it: