snapshot of https://github.com/ThreeDotsLabs/watermill.git (master, 2026-09-15; blobs > 131072B omitted)

tools/mill/README.md

@@ -0,0 +1,100 @@
+# mill - a simple CLI tool for Watermill
+
+`mill` is a CLI tool for the [Watermill](https://watermill.io) library.
+
+It has two basic functionalities, namely producing and consuming messages on the following
+Pub/Subs:
+
+1. Kafka
+2. Google Cloud Pub/Sub
+3. RabbitMQ
+
+See Watermill's [Supported Pub/Subs](https://watermill.io/pubsubs) for more details on how this works.
+
+## Installation
+
+To install this tool, just execute:
+
+```bash
+go install github.com/ThreeDotsLabs/watermill/tools/mill@latest
+```
+
+This will install a `mill` binary in your system.
+
+## Consume mode
+
+In consume mode, the tool subscribes to a topic/queue/subscription (nomenclature depending on the particular Pub/Sub provider)
+and prints the messages' payload to the standard output.
+
+Other outputs, for example ones that add a timestamp or preserve UUIDs or metadata, are easily attainable by modification
+of the marshaling function of the `io.Publisher` of the `consumeCmd`.
+
+## Produce mode
+
+In produce mode, subsequent lines of data from the standard input are transformed into messages outgoing to the requested
+provider's topic/exchange. 
+
+The message's payload is set to the line from stdin, the UUID is auto-generated and the metadata is empty.
+
+Similarly, the contents of the message could be parsed differently from stdin, by modification
+of the unmarshaling function of the `io.Subscriber` of the `produceCmd`.
+
+## Usage
+
+The basic syntax of the tool is:
+
+```bash
+mill <provider> <command>
+```
+
+with the appropriate flags regulating the specific behaviour of each command.
+
+`command` is usually one of `produce` or `consume`, but some providers may handle additional commands
+that are specific for them.
+
+The flags are context-specific, so the best way to find out about them is to use the `-h` flag and study 
+which flags are available/required for the specific context and act accordingly.
+
+### Advanced usage
+
+A neat feature of producers and consumers is that you can use the power of stdin/stdout piping for stuff like:
+
+```bash
+myservice | tee myservice.log | mill kafka produce -t myservice-logs --brokers kafka-host:8082 
+```
+
+And on another host:
+
+```bash
+mill kafka consume -t myservice-logs --brokers kafka-host:8082 >> myservice.log
+```
+
+In the above example, the host on which `myservice` runs has its own copy of `myservice.log` and any host that consumes
+from the kafka topic will replicate the log entries in their local copy.
+
+
+## Additional functionalities
+
+### Google Cloud Pub/Sub
+
+#### Adding/Removing subscriptions
+
+You can use `mill` to create/remove subscriptions for Google Cloud Pub/Sub:
+
+```bash
+mill googlecloud subscription add -t <topic> <subscription_id>
+
+mill googlecloud subscription rm <subscription_id>
+```
+
+Additional flags are available for `subscription add` to regulate the newly created subscription's settings.
+
+#### Listing subscriptions
+
+You can use `mill` to list existing subscriptions:
+
+```bash
+mill googlecloud subscription ls [-t topic]
+```
+
+The topic is optional. If omitted, all topics will be listed with their subscriptions.