Enhance README.md with more examples & fix typos

README.md

@@ -74,22 +74,28 @@ able to compile catalogs on the new Master. This is useful when upgrading Puppet
 
 To upload facts to PuppetDB on a Master see the [Upload facts](#upload-facts-to-puppetdb) script.
 
-
 ## Setup
 
 
 ### Set up node discovery
 
-
 Node discovery requires an access to the PuppetDB. You'll need either:
 
 * have an unencrypted access to PuppetDB (port 8080, local or proxified)
 * generate a set key and certificate signed by the Puppet CA to access the
   PuppetDB
 
+PuppetDB has an (optional) [allowlist](https://www.puppet.com/docs/puppetdb/7/configure.html#certificate-allowlist)
+for certificates that are allowed to connect to the database. It's located at
+`/etc/puppetlabs/puppetdb/certificate-allowlist`. in Puppet Enterprise you can
+configure it like this to allow a specific certificate:
 
-### Set up auth.conf
+```yaml
+puppet_enterprise::profile::puppetdb::allowlisted_certnames:
+  - catalog-diff
+```
 
+### Set up auth.conf
 
 Once you have set up the discovery, you need to allow access to the "diff" node to
 compile the catalogs for all nodes on both your old and new masters.
@@ -102,7 +108,6 @@ If there is an existing reference i.e. the $1 back reference for machines to
 compile their own catalog then simply add another line with the certificate
 name of the diff machine. As mentioned this can be the new master as required.
 
-
 E.g. if you're using Puppet 5, you should have something like:
 
 ```ruby
@@ -159,14 +164,14 @@ in Hiera/Puppet code required using the certless API. From the
 ## Usage
 
 
-Example:
-
+Example: diff catalogs for `node1.example.com` & `node2.example.com` between
+puppetserver `puppet5.example.com`, `puppet6.example.com`. The old catalog will
+be fetched from PuppetDB, the new one will be compiled:
 
 ```shell
 $ puppet module install puppet-catalog_diff
 $ puppet catalog diff \
      puppet5.example.com:8140/production puppet6.example.com:8140/production \
-     --use_puppetdb \
      --filter_old_env \
      --old_catalog_from_puppetdb \
      --certless \
@@ -181,9 +186,26 @@ $ puppet catalog diff \
      --debug \
      \ #--fact_search kernel='Darwin' \
      --threads 50 \
-     \ #--node_list=node1.example.come,node2.example.com
+     \ #--node_list=node1.example.com,node2.example.com
+```
+
+Example: Compare to local catalogs for `node1.example.com` (we recommend absolute paths):
+
+```shell
+$ puppet catalog diff /foo/old/node1.example.com.json /foo/new/node1.example.com.json
 ```
 
+You can generate them on an agent in a serverless setup:
+
+```shell
+puppet catalog compile --render-as json
+```
+
+As an alternative an agent can also download its catalog and store it locally:
+
+```shell
+puppet catalog download
+```
 
 ### Multi threaded compile requests
 

lib/puppet/face/catalog/diff.rb

@@ -205,7 +205,7 @@
         nodes[node_name] = Puppet::CatalogDiff::Differ.new(catalog1, catalog2).diff(options)
 
       else
-        # User passed use two hostnames
+        # User passed us two hostnames
         old_catalogs = Dir.mktmpdir("#{catalog1.tr('/', '_')}-")
         new_catalogs = Dir.mktmpdir("#{catalog2.tr('/', '_')}-")
         pull_output = Puppet::Face[:catalog, '0.0.1'].pull(