docs: Added usage notes (#16)

Ported the usage notes to the docs here.

docs/SUMMARY.md

@@ -23,10 +23,10 @@
   - [Prerequisites]()
   - [Installation]()
   - [Configuration]()
-- [Interacting with Walrus]()
-  - [Using the client CLI]()
-  - [Using the client JSON API]()
-  - [Using the client daemon]()
+- [Interacting with Walrus](interacting.md)
+  - [Using the client CLI](client-cli.md)
+  - [Using the client JSON API](json-api.md)
+  - [Using the client HTTP API](web-api.md)
 - [Examples]()
 
 # Walrus sites

docs/client-cli.md

@@ -0,0 +1,17 @@
+# Using the Walrus client
+
+The `walrus` binary can be used to interact with Walrus as a client. To use it, you need a Walrus
+configuration and a Sui wallet.
+Detailed usage information is available through
+
+```sh
+walrus --help
+```
+
+Storing and reading blobs from Walrus can be achieved through the following commands:
+
+```sh
+CONFIG=working_dir/client_config.yaml # adjust for your configuration file
+walrus -c $CONFIG store <some file> # store a file
+walrus -c $CONFIG read <some blob ID> # read a blob
+```

docs/interacting.md

@@ -0,0 +1,7 @@
+# Interacting with Walrus
+
+We provide 3 ways to interact directly with the Walrus storage system:
+
+- Through the walrus [client command line interface (CLI)](client-cli.md).
+- Through a [JSON API](json-api.md) of the walrus CLI.
+- Through an [HTTP API](web-api.md) exposed by the walrus client daemon.

docs/json-api.md

@@ -0,0 +1,39 @@
+# JSON mode
+
+All Walrus client commands (except, currently, the `info` command) are available in JSON mode.
+In this mode, all the command line flags of the original CLI command can be specified in JSON
+format. The JSON mode therefore simplifies programmatic access to the CLI.
+
+For example, to store a blob, run:
+
+```sh
+walrus json \
+    '{
+        "config": "working_dir/client_config.yaml",
+        "command": {
+            "store": {
+                "file": "README.md"
+            }
+        }
+    }'
+```
+
+or, to read a blob knowing the blob ID:
+
+```sh
+walrus json \
+    '{
+        "config": "working_dir/client_config.yaml",
+        "command": {
+            "read": {
+                "blob_id": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo"
+            }
+        }
+    }'
+```
+
+The `json` command also accepts input from `stdin`.
+
+The output of a `json` command will itself be JSON-formatted, again to simplify parsing the results
+in a programmatic way. For example, the JSON output can be piped to the `jq` command for parsing and
+manually extracting relevant fields.

docs/web-api.md

@@ -0,0 +1,41 @@
+# Client Daemon mode & HTTP API
+
+In addition to the CLI mode, the Walrus client offers a *daemon mode*. In this mode, it runs a
+simple web server offering HTTP interfaces to store and read blobs.
+
+## Starting the daemon
+
+You can run the daemon with
+different sets of API endpoints through one of the following commands:
+
+```sh
+ADDRESS="127.0.0.1:31415" # bind the daemon to localhost and port 31415
+walrus -c $CONFIG aggregator -b $ADDRESS # run an aggregator to read blobs
+walrus -c $CONFIG publisher -b $ADDRESS # run a publisher to store blobs
+walrus -c $CONFIG daemon -b $ADDRESS # run a daemon combining an aggregator and a publisher
+```
+
+The aggregator provides all read APIs, the publisher all the store APIs, and daemon provides both.
+Note that the aggregator does not perform Sui on-chain actions, and therefore consumes no gas.
+However, the publisher does perform actions on-chain and will consume gas. It is therefore important
+to ensure only authorized parties may access it, or other measures to manage gas costs.
+
+## HTTP API Usage
+
+You can then interact with the daemon through simple HTTP requests. For example, with
+[cURL](https://curl.se), you can store blobs as follows:
+
+```sh
+curl -X PUT "http://$ADDRESS/v1/store" -d "some string" # store the string `some string` for 1 storage epoch
+curl -X PUT "http://$ADDRESS/v1/store?epochs=5" -d @"some/file" # store file `some/file` for 5 storage epochs
+```
+
+Blobs may be read using the following cURL command:
+
+```sh
+curl "http://$ADDRESS/v1/<some blob ID>" # read a blob from Walrus (with aggregator or daemon)
+```
+
+Modern browsers will attempt to sniff the content type for such resources, and will generally do a
+good job of inferring content types for media. However, the aggregator on purpose prevents such
+sniffing from inferring dangerous executable types such as javascript or style sheet types.