From 31fdfebca99476a0fcae544b92f37ea0eac8e656 Mon Sep 17 00:00:00 2001
From: Guillaume Pasquet <dev@etenil.net>
Date: Wed, 16 Feb 2022 10:18:45 +0000
Subject: Update documentation, prep for release

---
 Cargo.toml |   4 +++
 README.md  | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 104 insertions(+), 3 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 2cabd7b..4e1b893 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,6 +2,10 @@
 name = "barb"
 version = "0.1.0"
 edition = "2018"
+license = "GPL-3.0-or-later"
+description = "Command-line tool to perform file-based HTTP(s) requests."
+repository = "https://gitlab.com/guillaume54/barb"
+readme = "README.md"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
diff --git a/README.md b/README.md
index f8663f4..a47d00d 100644
--- a/README.md
+++ b/README.md
@@ -3,14 +3,111 @@ BARB
 
 ![Barb logo](doc/logo-readme.png)
 
-Barb is a file-based API query tool written in Rust that works nicely with version control and fits into unix terminal usage.
+Barb is a file-based API query tool that works nicely with version control and fits into UNIX terminal usage.
 
 ## Example usage
 
-(not working yet)
+```
+barb <file 1> <file 2> ... <file n>
+```
+
+### CLI options
+
+- `-a, --all-headers`: Print all headers, request and response
+- `-b, --body`: Only print the response body
+- `-h, --headers`: Only print the response headers
+- `-r, --raw`: Don't format the response body
+- `-V, --version`: Print the software version
+
+## Barb format
+
+Barb uses a custom file format to perform requests. Each file contains _one_ request and is started by a request preamble. Example:
+
+```
+#POST^http://my-blog.com/posts
+#Authorization: TOKEN {API_TOKEN}
+
+{
+    "title": "A post",
+    "content": "My pretty blog post"
+}
+
+```
+
+The preamble contains the directives relevant to performing the request, such as the method, URL and headers. The preamble _must end with an empty line_.
 
+### Verb line
+
+The verb line indicates to _barb_ what sort of request to perform and where to. It follows this rigid format:
+
+```
+#<METHOD>^<URL>
+```
+
+The `URL` supports variable substitution, but `METHOD` does not.
+
+Supported methods are:
+
+- GET
+- POST
+- PUT
+- DELETE
+- PATCH
+
+### Headers
+
+Headers are formatted as follows:
+
+```
+#<HEADER NAME>: <HEADER VALUE>
 ```
-barb <file1> <file2>
+
+The `HEADER VALUE` supports variable substitution, `HEADER NAME` does not.
+
+There can be none or many headers.
+
+### Filter
+
+!!! Not operational at this time
+
+Barb will support JQ filtering of the response body. This has the following format:
+
+```
+#|<JQ FILTER>
+```
+
+The `JQ FILTER` supports variable substitution.
+
+### Body
+
+Anything after the preamble is considered as a body and will be send in the request for the following methods:
+
+- PUT
+- POST
+- PATCH
+
+Body does not support variable substitution.
+
+### Variable substitution
+
+Barb can include environment variable values into the requests with the following placeholder format:
+
+```
+{VARIABLE NAME}
+```
+
+Which allows to do the following:
+
+```
+$ export BASE_URL="http://127.0.0.1:8000"
+$ cat api-status.barb
+#GET^{BASE_URL}/api/v1/status
+
+$ barb api-status.barb
+200 OK GET http://127.0.0.1:8000/api/v1/status
+{
+    "status": "OK"
+}
 ```
 
 ## Credits
-- 
cgit v1.2.3