add to the readme

README.md

@@ -42,7 +42,65 @@ Flags:
 Use "bitmaskcfg [command] --help" for more information about a command.
 ```
 
+## Examples
+
+### Fetching a list of locations 
+
+```
+❯ ./bitmaskcfg locations --host menshen.example.org ls
+4:08PM INF Using uTLS client with direct connection
+4:08PM INF Using DoH resolver: 208.67.222.222
+ID  location
+1   amsterdam
+2   miami
+3   montreal
+4   newyorkcity
+5   paris
+6   seattle
+```
+
+### Picking the best location
+
+This command will first fetch gateways for a subset of locations, ping them and
+then evaluate the best one based on the measured latency:
+
+```
+❯ ./bitmaskcfg locations --host menshen.example.org best
+4:09PM INF Picking best location...
+4:09PM INF using host: menshen.example.org
+4:09PM INF Using uTLS client with direct connection
+4:09PM INF Using DoH resolver: 208.67.222.222
+Best: paris (163.172.58.132)
+```
+
+### Add an introducer
+
+Add a new introducer:
+
+```
+❯ ./bitmaskcfg introducer add litteintroducer "obfsvpnintro://1.2.3.4:8443/?cert=neVUoIX/qGFP59HAz8M5XZAt9vbHIXPx5W68Bo6iZdHaqs9Ec3LTTGV8unhLJslVC0mmGA&kcp=1&fqdn=menshen.asdf.network"
+```
+
+### Use the introducer to communicate with the API
+
+After successfully adding an introducer to the database, it can be used to contact the API:
+
+```
+❯ ./bitmaskcfg introducer ls
+ID  Selected  Name              Created       Last used
+11            littleintroducer  1 min ago     never
+
+❯ ./bitmaskcfg locations best --introducer littleintroducer
+4:23PM INF Picking best location...
+4:23PM INF using host: menshen.example.org
+4:23PM WRN --host=menshen.example.org will be overriden with --fqdn=other.example.org because introducer has precedence
+4:23PM INF Using obfuscated http client
+Best: paris (163.172.83.106)
+``` 
+
+
 # bitmask-linux tool
 
-Additionally, refer to the documentation in `cmd/bitmask-linux` for an experimental linux client.
+Additionally, refer to the documentation in `cmd/bitmask-linux` for an
+experimental linux client using `openvpn3` and `dbus`.