From ce75930a3c1a47a6d1ad4b0e291d9bf58420585d Mon Sep 17 00:00:00 2001
From: ssube <seansube@gmail.com>
Date: Sat, 15 Jun 2019 21:08:21 -0500
Subject: [PATCH] docs: expand examples

---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 73 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index d880d41..be9aa72 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,21 @@
 # SALTY DOG
 
-JSON **s**chema **a**nalysis, **l**inting, and **t**ransformation for **Y**AML, featuring **d**efaults, **o**ptional
-fields, and other **g**ood stuff.
+YAML linter/validator.
+
+Or, as an acronym, JSON **s**chema **a**nalysis, **l**inting, and **t**ransformation for **Y**AML, featuring
+**d**efaults, **o**ptional fields, and other **g**ood stuff.
 
 - [SALTY DOG](#salty-dog)
   - [Build](#build)
   - [Usage](#usage)
+    - [Validate](#validate)
+      - [Validate File](#validate-file)
+      - [Validate URL](#validate-url)
+      - [Validate Rules](#validate-rules)
     - [Options](#options)
       - [Count](#count)
+      - [Dest](#dest)
+      - [Format](#format)
       - [Exclude](#exclude)
         - [Exclude Level](#exclude-level)
         - [Exclude Name](#exclude-name)
@@ -22,6 +30,8 @@ fields, and other **g**ood stuff.
 
 ## Build
 
+This project is written in Typescript and requires Node to be built.
+
 ```shell
 > git clone git@github.com:ssube/salty-dog.git
 > make
@@ -29,36 +39,60 @@ fields, and other **g**ood stuff.
 
 ## Usage
 
-To validate the rules in the `rules/` directory:
+### Validate
 
-```shell
-> make run-rules
-...
-{"name":"salty-dog","hostname":"cerberus","pid":29403,"level":30,"msg":"all rules passed","time":"2019-06-16T00:56:55.132Z","v":0}
-```
+`salty-dog` can validate JSON and YAML from files and streams, and emit it to a file or stream (with logs going
+elsewhere).
+
+#### Validate File
 
 To validate a file:
 
 ```shell
-> cat rules/examples/kubernetes-require-resources-fail.yml |\
-    salty-dog \
-      --rules rules/kubernetes.yml \
-      --source - \
-      --tag important |\
-    ./node_modules/.bin/bunyan
+> salty-dog \
+    --rules rules/kubernetes.yml \
+    --source rules/examples/kubernetes-require-resources-fail.yml \
+    --tag important
 
+...
 [2019-06-15T23:56:04.764Z] ERROR: salty-dog/22211 on cerberus: some rules failed (errors=1)
 
-> cat rules/examples/kubernetes-require-resources-pass.yml |\
-    salty-dog \
-      --rules rules/kubernetes.yml \
-      --source - \
-      --tag important |\
-    ./node_modules/.bin/bunyan
+> cat rules/examples/kubernetes-require-resources-pass.yml | salty-dog \
+    --rules rules/kubernetes.yml \
+    --source - \
+    --tag important
 
+...
 [2019-06-15T23:53:34.223Z]  INFO: salty-dog/19839 on cerberus: all rules passed
 ```
 
+#### Validate URL
+
+To validate a URL:
+
+```shell
+> curl https://raw.githubusercontent.com/ssube/k8s-shards/master/roles/apps/gitlab/server/templates/ingress.yml | salty-dog \
+    --rules rules/kubernetes.yml \
+    --source - \
+    --tag important | kubectl apply --dry-run -f -
+
+...
+{"name":"salty-dog","hostname":"cerberus","pid":7860,"level":30,"msg":"all rules passed","time":"2019-06-16T02:04:37.797Z","v":0}
+ingress.extensions/gitlab created (dry run)
+...
+```
+
+#### Validate Rules
+
+To validate the rules in the `rules/` directory using the meta-rules:
+
+```shell
+> make run-rules
+
+...
+{"name":"salty-dog","hostname":"cerberus","pid":29403,"level":30,"msg":"all rules passed","time":"2019-06-16T00:56:55.132Z","v":0}
+```
+
 ### Options
 
 #### Count
@@ -67,6 +101,25 @@ To validate a file:
 
 Exit with the error count (max of 255) rather than `0` or `1`.
 
+#### Dest
+
+- Alias: `d`
+- Default: `-`
+
+Path to write output data.
+
+Defaults to stdout (`-`).
+
+#### Format
+
+- Default: `yaml`
+
+Output format.
+
+Options:
+
+- `yaml`
+
 #### Exclude
 
 Excludes take priority over includes: a rule matching some of both will be excluded.