octocatalog-diff 0.6.1 → 1.0.0

data/doc/dev/api/v1/objects/override.md

@@ -0,0 +1,30 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::API::V1::Override
+
+## Overview
+
+`OctocatalogDiff::API::V1::Override` is an object that represents a user-supplied fact or ENC parameter that will be used when compiling a catalog.
+
+## Constructor
+
+#### `#new(<Hash> { key: <String>, value: <Object> })`
+
+The hash must contain the following keys:
+
+- `:key` (String) - The name of the fact or ENC parameter (e.g. `operatingsystem` or `parameters::fooclass::fooparam`)
+- `:value` (?) - The value of the fact or ENC parameter
+
+See also: `#create_from_input`
+
+## Methods
+
+#### `#create_from_input(<String> key=value)` (OctocatalogDiff::API::V1::Override)
+
+Parses the string (see [Overriding facts](/doc/advanced-override-facts.md) for the format to use). Returns a `OctocatalogDiff::API::V1::Override` object with key and value parsed from the string.
+
+#### `#key` (String)
+
+Returns the key as supplied in the constructor.
+
+#### `#value` (?)
+
+Returns the value as supplied in the constructor.

data/doc/dev/how-to-add-options.md

@@ -7,9 +7,9 @@ This document contains a checklist and guidance to adding new command line optio
 Please copy and paste this text into your Pull Request. This will create boxes for each step along the way, which you can then check off when complete.
 
 ```
-- [ ] REQUIRED: Add new file in `lib/octocatalog-diff/catalog-diff/cli/options`
-- [ ] REQUIRED: Add corresponding test in `spec/octocatalog-diff/tests/catalog-diff/cli/options`
-- [ ] OPTIONAL: Add default value in `lib/octocatalog-diff/catalog-diff/cli.rb`
+- [ ] REQUIRED: Add new file in `lib/octocatalog-diff/cli/options`
+- [ ] REQUIRED: Add corresponding test in `spec/octocatalog-diff/tests/cli/options`
+- [ ] OPTIONAL: Add default value in `lib/octocatalog-diff/cli.rb`
 - [ ] OPTIONAL: Add configuration example in `examples/octocatalog-diff.cfg.rb`
 - [ ] REQUIRED: Add code to implement your option in `lib`
 - [ ] REQUIRED: Add corresponding tests for code to implement your option in `spec/octocatalog-diff/tests`
@@ -20,7 +20,7 @@ Please copy and paste this text into your Pull Request. This will create boxes f
 
 ### Create option parser
 
-Option parsers are created in [`lib/octocatalog-diff/catalog-diff/cli/options`](/lib/octocatalog-diff/catalog-diff/cli/options).
+Option parsers are created in [`lib/octocatalog-diff/cli/options`](/lib/octocatalog-diff/cli/options).
 
 Your option should have a "long form" that contains dashes and not underscores. For example, you should prefer `--your-new-option` and NOT use `--your_new_option`.
 
@@ -32,23 +32,23 @@ If you are creating a binary (yes-no) option, please recognize both `--your-new-
 
 We recommend copying prior art as a template:
 
-- For a binary (yes-no) option, look at [`quiet.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/quiet.rb).
+- For a binary (yes-no) option, look at [`quiet.rb`](/lib/octocatalog-diff/cli/options/quiet.rb).
 
-- For an option that takes an integer parameter, look at [`retry_failed_catalog.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/retry_failed_catalog.rb).
+- For an option that takes an integer parameter, look at [`retry_failed_catalog.rb`](/lib/octocatalog-diff/cli/options/retry_failed_catalog.rb).
 
-- For an option that takes an string parameter, look at [`bootstrap_script.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_script.rb).
+- For an option that takes an string parameter, look at [`bootstrap_script.rb`](/lib/octocatalog-diff/cli/options/bootstrap_script.rb).
 
-- For an option that takes an array or can be specified more than once, look at [`bootstrap_environment.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_environment.rb).
+- For an option that takes an array or can be specified more than once, look at [`bootstrap_environment.rb`](/lib/octocatalog-diff/cli/options/bootstrap_environment.rb).
 
-If you can do simple validation of the argument, such as making sure the argument (if specified) matches a particular regular expression or is one of a particular set of values, please do that within the option file. For example, look at [`facts_terminus.rb`](/lib/octocatalog-diff/catalog-diff/cli/options/facts_terminus.rb).
+If you can do simple validation of the argument, such as making sure the argument (if specified) matches a particular regular expression or is one of a particular set of values, please do that within the option file. For example, look at [`facts_terminus.rb`](/lib/octocatalog-diff/cli/options/facts_terminus.rb).
 
 ### Create test for option parser
 
-Option parser tests are created in [`spec/octocatalog-diff/tests/catalog-diff/cli/options`](/spec/octocatalog-diff/tests/catalog-diff/cli/options).
+Option parser tests are created in [`spec/octocatalog-diff/tests/cli/options`](/spec/octocatalog-diff/tests/cli/options).
 
 If you used an existing option as a reference for your new code, consider using that option's test as a reference for your test. We have some methods, e.g. `test_with_true_false_option`, to avoid repetitive code for common patterns.
 
-If you have handled any edge cases, e.g. input validation, please add a test that expects an error when input is provided that does not match your validation. For example, look at [`parser_spec.rb`](/spec/octocatalog-diff/tests/catalog-diff/cli/options/parser_spec.rb).
+If you have handled any edge cases, e.g. input validation, please add a test that expects an error when input is provided that does not match your validation. For example, look at [`parser_spec.rb`](/spec/octocatalog-diff/tests/cli/options/parser_spec.rb).
 
 ### Add default value (OPTIONAL)
 
@@ -56,7 +56,7 @@ Unless specifically cleared with the project maintainers, adding a new option sh
 
 In other words, if someone invokes the program *without* specifying your option, it should behave in the same way as it did before your option was ever added.
 
-If you need to set a default value for your option, do so in [`lib/octocatalog-diff/catalog-diff/cli.rb`](/lib/octocatalog-diff/catalog-diff/cli.rb). Items should be added to DEFAULT_OPTIONS *only if* a value is required even if your option is not provided, or if you are defaulting something to *true* but providing an option to make it false.
+If you need to set a default value for your option, do so in [`lib/octocatalog-diff/cli.rb`](/lib/octocatalog-diff/cli.rb). Items should be added to DEFAULT_OPTIONS *only if* a value is required even if your option is not provided, or if you are defaulting something to *true* but providing an option to make it false.
 
 ### Add configuration example (OPTIONAL)
 

data/doc/optionsref.md

@@ -27,7 +27,7 @@ Usage: octocatalog-diff [command line options]
         --bootstrap-then-exit        Bootstrap from-dir and/or to-dir and then exit
         --[no-]color                 Enable/disable colors in output
     -o, --output-file FILENAME       Output results into FILENAME
-        --output-format FORMAT       Output format: text,json
+        --output-format FORMAT       Output format: text,json,legacy_json
     -d, --[no-]debug                 Print debugging messages to STDERR
     -q, --[no-]quiet                 Quiet (no status messages except errors)
         --ignore "Type1[Title1],Type2[Title2],..."
@@ -118,6 +118,12 @@ Usage: octocatalog-diff [command line options]
                                      Full path to key file for SSL client auth to Puppet Master for the to branch
         --from-puppet-master-ssl-client-key STRING
                                      Full path to key file for SSL client auth to Puppet Master for the from branch
+        --enc-override STRING1[,STRING2[,...]]
+                                     Override parameter from ENC globally
+        --to-enc-override STRING1[,STRING2[,...]]
+                                     Override parameter from ENC for the to branch
+        --from-enc-override STRING1[,STRING2[,...]]
+                                     Override parameter from ENC for the from branch
         --pe-enc-url URL             Base URL for Puppet Enterprise ENC endpoint
         --pe-enc-token TOKEN         Token to access the Puppet Enterprise ENC API
         --pe-enc-token-file PATH     Path containing token for PE node classifier, relative or absolute
@@ -169,7 +175,7 @@ Usage: octocatalog-diff [command line options]
       Use an alternate base directory (git checkout of puppet repository)
     </td>
     <td valign=top>
-      Option to set the base checkout directory of puppet repository (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/basedir.rb">basedir.rb</a>)
+      Option to set the base checkout directory of puppet repository (<a href="../lib/octocatalog-diff/cli/options/basedir.rb">basedir.rb</a>)
     </td>
   </tr>
 
@@ -182,7 +188,7 @@ Usage: octocatalog-diff [command line options]
     </td>
     <td valign=top>
       Option to bootstrap the current directory (by default, the bootstrap script is NOT
-run when the catalog builds in the current directory). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_current.rb">bootstrap_current.rb</a>)
+run when the catalog builds in the current directory). (<a href="../lib/octocatalog-diff/cli/options/bootstrap_current.rb">bootstrap_current.rb</a>)
     </td>
   </tr>
 
@@ -194,7 +200,7 @@ run when the catalog builds in the current directory). (<a href="../lib/octocata
       Bootstrap script environment variables in key=value format
     </td>
     <td valign=top>
-      Allow the bootstrap environment to be set up via the command line. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_environment.rb">bootstrap_environment.rb</a>)
+      Allow the bootstrap environment to be set up via the command line. (<a href="../lib/octocatalog-diff/cli/options/bootstrap_environment.rb">bootstrap_environment.rb</a>)
     </td>
   </tr>
 
@@ -208,7 +214,7 @@ run when the catalog builds in the current directory). (<a href="../lib/octocata
     <td valign=top>
       Allow specification of a bootstrap script. This runs after checking out the directory, and before running
 puppet there. Good for running librarian to install modules, and anything else site-specific that needs
-to be done. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_script.rb">bootstrap_script.rb</a>)
+to be done. (<a href="../lib/octocatalog-diff/cli/options/bootstrap_script.rb">bootstrap_script.rb</a>)
     </td>
   </tr>
 
@@ -220,7 +226,7 @@ to be done. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap
       Bootstrap from-dir and/or to-dir and then exit
     </td>
     <td valign=top>
-      Option to bootstrap directories and then exit (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap_then_exit.rb">bootstrap_then_exit.rb</a>)
+      Option to bootstrap directories and then exit (<a href="../lib/octocatalog-diff/cli/options/bootstrap_then_exit.rb">bootstrap_then_exit.rb</a>)
     </td>
   </tr>
 
@@ -233,7 +239,7 @@ to be done. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrap
     </td>
     <td valign=top>
       Allow (or create) directories that are already bootstrapped. Handy to allow "bootstrap once, build many"
-to save time when diffing multiple catalogs on this system. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrapped_dirs.rb">bootstrapped_dirs.rb</a>)
+to save time when diffing multiple catalogs on this system. (<a href="../lib/octocatalog-diff/cli/options/bootstrapped_dirs.rb">bootstrapped_dirs.rb</a>)
     </td>
   </tr>
 
@@ -246,7 +252,7 @@ to save time when diffing multiple catalogs on this system. (<a href="../lib/oct
     </td>
     <td valign=top>
       Allow (or create) directories that are already bootstrapped. Handy to allow "bootstrap once, build many"
-to save time when diffing multiple catalogs on this system. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/bootstrapped_dirs.rb">bootstrapped_dirs.rb</a>)
+to save time when diffing multiple catalogs on this system. (<a href="../lib/octocatalog-diff/cli/options/bootstrapped_dirs.rb">bootstrapped_dirs.rb</a>)
     </td>
   </tr>
 
@@ -259,7 +265,7 @@ to save time when diffing multiple catalogs on this system. (<a href="../lib/oct
     </td>
     <td valign=top>
       Cache a bootstrapped checkout of 'master' and use that for time-saving when the SHA
-has not changed. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/cached_master_dir.rb">cached_master_dir.rb</a>)
+has not changed. (<a href="../lib/octocatalog-diff/cli/options/cached_master_dir.rb">cached_master_dir.rb</a>)
     </td>
   </tr>
 
@@ -273,7 +279,7 @@ has not changed. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/cach
     </td>
     <td valign=top>
       When set, --catalog-only will only compile the catalog for the 'to' branch, and skip any
-diffing activity. The catalog will be printed to STDOUT or written to the output file. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/catalog_only.rb">catalog_only.rb</a>)
+diffing activity. The catalog will be printed to STDOUT or written to the output file. (<a href="../lib/octocatalog-diff/cli/options/catalog_only.rb">catalog_only.rb</a>)
     </td>
   </tr>
 
@@ -286,7 +292,7 @@ diffing activity. The catalog will be printed to STDOUT or written to the output
       Enable/disable colors in output
     </td>
     <td valign=top>
-      Color printing option (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/color.rb">color.rb</a>)
+      Color printing option (<a href="../lib/octocatalog-diff/cli/options/color.rb">color.rb</a>)
     </td>
   </tr>
 
@@ -302,7 +308,7 @@ diffing activity. The catalog will be printed to STDOUT or written to the output
       When a file is specified with `source => 'puppet:///modules/something/foo.txt'`, remove
 the 'source' attribute and populate the 'content' attribute with the text of the file.
 This allows for a diff of the content, rather than a diff of the location, which is
-what is most often desired. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/compare_file_text.rb">compare_file_text.rb</a>)
+what is most often desired. (<a href="../lib/octocatalog-diff/cli/options/compare_file_text.rb">compare_file_text.rb</a>)
     </td>
   </tr>
 
@@ -316,7 +322,7 @@ what is most often desired. (<a href="../lib/octocatalog-diff/catalog-diff/cli/o
       Print debugging messages to STDERR
     </td>
     <td valign=top>
-      Debugging option (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/debug.rb">debug.rb</a>)
+      Debugging option (<a href="../lib/octocatalog-diff/cli/options/debug.rb">debug.rb</a>)
     </td>
   </tr>
 
@@ -330,7 +336,7 @@ what is most often desired. (<a href="../lib/octocatalog-diff/catalog-diff/cli/o
     <td valign=top>
       Option to print debugging output for the bootstrap script in addition to the normal
 debugging output. Note that `--debug` must also be enabled for this option to have
-any effect. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/debug_bootstrap.rb">debug_bootstrap.rb</a>)
+any effect. (<a href="../lib/octocatalog-diff/cli/options/debug_bootstrap.rb">debug_bootstrap.rb</a>)
     </td>
   </tr>
 
@@ -342,7 +348,7 @@ any effect. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/debug_boo
       Print default header with output
     </td>
     <td valign=top>
-      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/header.rb">header.rb</a>)
+      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/cli/options/header.rb">header.rb</a>)
     </td>
   </tr>
 
@@ -358,7 +364,7 @@ any effect. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/debug_boo
       Toggle on or off the display of data type changes when the string representation
 is the same. For example with this enabled, '42' (the string) and 42 (the integer)
 will be displayed as a difference. With this disabled, this is not displayed as a
-difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_datatype_changes.rb">display_datatype_changes.rb</a>)
+difference. (<a href="../lib/octocatalog-diff/cli/options/display_datatype_changes.rb">display_datatype_changes.rb</a>)
     </td>
   </tr>
 
@@ -371,7 +377,7 @@ difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_d
       Display parameters and other details for added resources
     </td>
     <td valign=top>
-      Provide ability to display details of 'added' resources in the output. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_detail_add.rb">display_detail_add.rb</a>)
+      Provide ability to display details of 'added' resources in the output. (<a href="../lib/octocatalog-diff/cli/options/display_detail_add.rb">display_detail_add.rb</a>)
     </td>
   </tr>
 
@@ -384,7 +390,7 @@ difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_d
       Show source file and line for each difference
     </td>
     <td valign=top>
-      Display source filename and line number for diffs (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_source_file_line.rb">display_source_file_line.rb</a>)
+      Display source filename and line number for diffs (<a href="../lib/octocatalog-diff/cli/options/display_source_file_line.rb">display_source_file_line.rb</a>)
     </td>
   </tr>
 
@@ -396,7 +402,7 @@ difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_d
       Path to ENC script, relative to checkout directory or absolute
     </td>
     <td valign=top>
-      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/enc.rb">enc.rb</a>)
+      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/cli/options/enc.rb">enc.rb</a>)
     </td>
   </tr>
 
@@ -408,7 +414,7 @@ difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_d
       Fact file to use instead of node lookup
     </td>
     <td valign=top>
-      Allow an existing fact file to be provided, to avoid pulling facts from PuppetDB. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/fact_file.rb">fact_file.rb</a>)
+      Allow an existing fact file to be provided, to avoid pulling facts from PuppetDB. (<a href="../lib/octocatalog-diff/cli/options/fact_file.rb">fact_file.rb</a>)
     </td>
   </tr>
 
@@ -422,7 +428,7 @@ difference. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/display_d
     <td valign=top>
       Get the facts terminus. Generally this is 'yaml' and a fact file will be loaded from PuppetDB or
 elsewhere in the environment. However it can be set to 'facter' which will run facter on the host
-on which this is running. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/facts_terminus.rb">facts_terminus.rb</a>)
+on which this is running. (<a href="../lib/octocatalog-diff/cli/options/facts_terminus.rb">facts_terminus.rb</a>)
     </td>
   </tr>
 
@@ -436,7 +442,7 @@ on which this is running. (<a href="../lib/octocatalog-diff/catalog-diff/cli/opt
     <td valign=top>
       Specify one or more filters to apply to the results of the catalog difference.
 For a list of available filters and further explanation, please refer to
-[Filtering results](/doc/advanced-filter.md). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/filters.rb">filters.rb</a>)
+<a href="advanced-filter.md">Filtering results</a>. (<a href="../lib/octocatalog-diff/cli/options/filters.rb">filters.rb</a>)
     </td>
   </tr>
 
@@ -450,7 +456,7 @@ For a list of available filters and further explanation, please refer to
     </td>
     <td valign=top>
       Set the 'from' and 'to' branches, which is used to compile catalogs. A branch of '.' means to use
-the current contents of the base code directory without any git checkouts. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/to_from_branch.rb">to_from_branch.rb</a>)
+the current contents of the base code directory without any git checkouts. (<a href="../lib/octocatalog-diff/cli/options/to_from_branch.rb">to_from_branch.rb</a>)
     </td>
   </tr>
 
@@ -463,7 +469,7 @@ the current contents of the base code directory without any git checkouts. (<a h
     </td>
     <td valign=top>
       If pre-compiled catalogs are available, these can be used to short-circuit the build process.
-These files must exist and be in Puppet catalog format. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/existing_catalogs.rb">existing_catalogs.rb</a>)
+These files must exist and be in Puppet catalog format. (<a href="../lib/octocatalog-diff/cli/options/existing_catalogs.rb">existing_catalogs.rb</a>)
     </td>
   </tr>
 
@@ -475,7 +481,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
       Path to ENC script (for the from catalog only)
     </td>
     <td valign=top>
-      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/enc.rb">enc.rb</a>)
+      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/cli/options/enc.rb">enc.rb</a>)
     </td>
   </tr>
 
@@ -488,7 +494,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
       Pull "from" catalog from PuppetDB instead of compiling
     </td>
     <td valign=top>
-      Set --from-puppetdb to pull most recent catalog from PuppetDB instead of compiling (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/from_puppetdb.rb">from_puppetdb.rb</a>)
+      Set --from-puppetdb to pull most recent catalog from PuppetDB instead of compiling (<a href="../lib/octocatalog-diff/cli/options/from_puppetdb.rb">from_puppetdb.rb</a>)
     </td>
   </tr>
 
@@ -500,7 +506,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
       Specify header for output
     </td>
     <td valign=top>
-      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/header.rb">header.rb</a>)
+      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/cli/options/header.rb">header.rb</a>)
     </td>
   </tr>
 
@@ -512,7 +518,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
       Relative path to hiera YAML file
     </td>
     <td valign=top>
-      Specify a relative path to the Hiera yaml file (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_config.rb">hiera_config.rb</a>)
+      Specify a relative path to the Hiera yaml file (<a href="../lib/octocatalog-diff/cli/options/hiera_config.rb">hiera_config.rb</a>)
     </td>
   </tr>
 
@@ -525,7 +531,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
     </td>
     <td valign=top>
       Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
-Puppet control repo template, the value of this should be 'hieradata', which is the default. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_path.rb">hiera_path.rb</a>)
+Puppet control repo template, the value of this should be 'hieradata', which is the default. (<a href="../lib/octocatalog-diff/cli/options/hiera_path.rb">hiera_path.rb</a>)
     </td>
   </tr>
 
@@ -537,7 +543,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       Path prefix to strip when munging hiera.yaml
     </td>
     <td valign=top>
-      Specify the path to strip off the datadir to munge hiera.yaml file (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_path_strip.rb">hiera_path_strip.rb</a>)
+      Specify the path to strip off the datadir to munge hiera.yaml file (<a href="../lib/octocatalog-diff/cli/options/hiera_path_strip.rb">hiera_path_strip.rb</a>)
     </td>
   </tr>
 
@@ -550,7 +556,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       Use PuppetDB facts from last run of hostname
     </td>
     <td valign=top>
-      Set hostname, which is used to look up facts in PuppetDB, and in the header of diff display. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hostname.rb">hostname.rb</a>)
+      Set hostname, which is used to look up facts in PuppetDB, and in the header of diff display. (<a href="../lib/octocatalog-diff/cli/options/hostname.rb">hostname.rb</a>)
     </td>
   </tr>
 
@@ -562,7 +568,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       More resources to ignore in format type[title]
     </td>
     <td valign=top>
-      Options used when comparing catalogs - set ignored changes. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/ignore.rb">ignore.rb</a>)
+      Options used when comparing catalogs - set ignored changes. (<a href="../lib/octocatalog-diff/cli/options/ignore.rb">ignore.rb</a>)
     </td>
   </tr>
 
@@ -574,7 +580,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       Attributes to ignore
     </td>
     <td valign=top>
-      Specify attributes to ignore (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/ignore_attr.rb">ignore_attr.rb</a>)
+      Specify attributes to ignore (<a href="../lib/octocatalog-diff/cli/options/ignore_attr.rb">ignore_attr.rb</a>)
     </td>
   </tr>
 
@@ -587,7 +593,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
     </td>
     <td valign=top>
       Provide ability to set one or more tags, which will cause catalog-diff
-to ignore any changes for any defined type where this tag is set. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/ignore_tags.rb">ignore_tags.rb</a>)
+to ignore any changes for any defined type where this tag is set. (<a href="../lib/octocatalog-diff/cli/options/ignore_tags.rb">ignore_tags.rb</a>)
     </td>
   </tr>
 
@@ -600,7 +606,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Include changes to tags in the diff output
     </td>
     <td valign=top>
-      Options used when comparing catalogs - tags are generally ignored; you can un-ignore them. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/include_tags.rb">include_tags.rb</a>)
+      Options used when comparing catalogs - tags are generally ignored; you can un-ignore them. (<a href="../lib/octocatalog-diff/cli/options/include_tags.rb">include_tags.rb</a>)
     </td>
   </tr>
 
@@ -612,7 +618,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Branch to cache
     </td>
     <td valign=top>
-      Allow override of the branch that is cached. This defaults to 'origin/master'. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/master_cache_branch.rb">master_cache_branch.rb</a>)
+      Allow override of the branch that is cached. This defaults to 'origin/master'. (<a href="../lib/octocatalog-diff/cli/options/master_cache_branch.rb">master_cache_branch.rb</a>)
     </td>
   </tr>
 
@@ -624,7 +630,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Disable ENC
     </td>
     <td valign=top>
-      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/enc.rb">enc.rb</a>)
+      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/cli/options/enc.rb">enc.rb</a>)
     </td>
   </tr>
 
@@ -636,7 +642,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Do not print a header
     </td>
     <td valign=top>
-      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/header.rb">header.rb</a>)
+      Provide ability to set custom header or to display no header at all (<a href="../lib/octocatalog-diff/cli/options/header.rb">header.rb</a>)
     </td>
   </tr>
 
@@ -648,7 +654,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Disable hiera config file installation
     </td>
     <td valign=top>
-      Specify a relative path to the Hiera yaml file (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_config.rb">hiera_config.rb</a>)
+      Specify a relative path to the Hiera yaml file (<a href="../lib/octocatalog-diff/cli/options/hiera_config.rb">hiera_config.rb</a>)
     </td>
   </tr>
 
@@ -661,7 +667,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
     </td>
     <td valign=top>
       Specify the path to the Hiera data directory (relative to the top level Puppet checkout). For Puppet Enterprise and the
-Puppet control repo template, the value of this should be 'hieradata', which is the default. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_path.rb">hiera_path.rb</a>)
+Puppet control repo template, the value of this should be 'hieradata', which is the default. (<a href="../lib/octocatalog-diff/cli/options/hiera_path.rb">hiera_path.rb</a>)
     </td>
   </tr>
 
@@ -673,7 +679,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
       Do not use any default hiera path strip settings
     </td>
     <td valign=top>
-      Specify the path to strip off the datadir to munge hiera.yaml file (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/hiera_path_strip.rb">hiera_path_strip.rb</a>)
+      Specify the path to strip off the datadir to munge hiera.yaml file (<a href="../lib/octocatalog-diff/cli/options/hiera_path_strip.rb">hiera_path_strip.rb</a>)
     </td>
   </tr>
 
@@ -686,7 +692,7 @@ Puppet control repo template, the value of this should be 'hieradata', which is
     </td>
     <td valign=top>
       Provide ability to set one or more tags, which will cause catalog-diff
-to ignore any changes for any defined type where this tag is set. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/ignore_tags.rb">ignore_tags.rb</a>)
+to ignore any changes for any defined type where this tag is set. (<a href="../lib/octocatalog-diff/cli/options/ignore_tags.rb">ignore_tags.rb</a>)
     </td>
   </tr>
 
@@ -699,7 +705,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Output results into FILENAME
     </td>
     <td valign=top>
-      Output file option (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/output_file.rb">output_file.rb</a>)
+      Output file option (<a href="../lib/octocatalog-diff/cli/options/output_file.rb">output_file.rb</a>)
     </td>
   </tr>
 
@@ -708,10 +714,12 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       <pre><code>--output-format FORMAT</code></pre>
     </td>
     <td valign=top>
-      Output format: text,json
+      Output format: text,json,legacy_json
     </td>
     <td valign=top>
-      Output format option (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/output_format.rb">output_format.rb</a>)
+      Output format option. 'text' is human readable text, 'json' is an array of differences
+identified by human readable keys (the preferred octocatalog-diff 1.x format), and 'legacy_json' is an
+array of differences, where each difference is an array (the octocatalog-diff 0.x format). (<a href="../lib/octocatalog-diff/cli/options/output_format.rb">output_format.rb</a>)
     </td>
   </tr>
 
@@ -724,7 +732,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Enable or disable parallel processing
     </td>
     <td valign=top>
-      Disable or enable parallel processing of catalogs. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/parallel.rb">parallel.rb</a>)
+      Disable or enable parallel processing of catalogs. (<a href="../lib/octocatalog-diff/cli/options/parallel.rb">parallel.rb</a>)
     </td>
   </tr>
 
@@ -736,7 +744,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Specify parser (default, future)
     </td>
     <td valign=top>
-      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/parser.rb">parser.rb</a>)
+      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/cli/options/parser.rb">parser.rb</a>)
     </td>
   </tr>
 
@@ -748,7 +756,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Specify parser (default, future)
     </td>
     <td valign=top>
-      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/parser.rb">parser.rb</a>)
+      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/cli/options/parser.rb">parser.rb</a>)
     </td>
   </tr>
 
@@ -760,7 +768,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       Specify parser (default, future)
     </td>
     <td valign=top>
-      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/parser.rb">parser.rb</a>)
+      Enable future parser for both branches or for just one (<a href="../lib/octocatalog-diff/cli/options/parser.rb">parser.rb</a>)
     </td>
   </tr>
 
@@ -774,7 +782,7 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
     <td valign=top>
       One or more environment variables that should be made available to the Puppet binary when parsing
 the catalog. For example, --pass-env-vars FOO,BAR will make the FOO and BAR environment variables
-available. Setting these variables is your responsibility outside of octocatalog-diff. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pass_env_vars.rb">pass_env_vars.rb</a>)
+available. Setting these variables is your responsibility outside of octocatalog-diff. (<a href="../lib/octocatalog-diff/cli/options/pass_env_vars.rb">pass_env_vars.rb</a>)
     </td>
   </tr>
 
@@ -788,7 +796,7 @@ available. Setting these variables is your responsibility outside of octocatalog
     <td valign=top>
       Specify the CA certificate for the Puppet Enterprise ENC. If specified, this will enable SSL verification
 that the certificate being presented has been signed by this CA, and that the common name
-matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_ssl_ca.rb">pe_enc_ssl_ca.rb</a>)
+matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/cli/options/pe_enc_ssl_ca.rb">pe_enc_ssl_ca.rb</a>)
     </td>
   </tr>
 
@@ -801,7 +809,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
     </td>
     <td valign=top>
       Specify the client certificate for connecting to the Puppet Enterprise ENC. This must be specified along with
---pe-enc-ssl-client-key in order to work. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_ssl_client_cert.rb">pe_enc_ssl_client_cert.rb</a>)
+--pe-enc-ssl-client-key in order to work. (<a href="../lib/octocatalog-diff/cli/options/pe_enc_ssl_client_cert.rb">pe_enc_ssl_client_cert.rb</a>)
     </td>
   </tr>
 
@@ -814,7 +822,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
     </td>
     <td valign=top>
       Specify the client key for connecting to Puppet Enterprise ENC. This must be specified along with
---pe-enc-ssl-client-cert in order to work. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_ssl_client_key.rb">pe_enc_ssl_client_key.rb</a>)
+--pe-enc-ssl-client-cert in order to work. (<a href="../lib/octocatalog-diff/cli/options/pe_enc_ssl_client_key.rb">pe_enc_ssl_client_key.rb</a>)
     </td>
   </tr>
 
@@ -829,7 +837,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
       Specify the access token to access the Puppet Enterprise ENC. Refer to
 https://docs.puppet.com/pe/latest/nc_forming_requests.html#authentication for
 details on generating and obtaining a token. Use this option to specify the text
-of the token. (Use --pe-enc-token-file to read the content of the token from a file.) (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_token.rb">pe_enc_token.rb</a>)
+of the token. (Use --pe-enc-token-file to read the content of the token from a file.) (<a href="../lib/octocatalog-diff/cli/options/pe_enc_token.rb">pe_enc_token.rb</a>)
     </td>
   </tr>
 
@@ -844,7 +852,7 @@ of the token. (Use --pe-enc-token-file to read the content of the token from a f
       Specify the access token to access the Puppet Enterprise ENC. Refer to
 https://docs.puppet.com/pe/latest/nc_forming_requests.html#authentication for
 details on generating and obtaining a token. Use this option if the token is stored
-in a file, to read the content of the token from the file. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_token_file.rb">pe_enc_token_file.rb</a>)
+in a file, to read the content of the token from the file. (<a href="../lib/octocatalog-diff/cli/options/pe_enc_token_file.rb">pe_enc_token_file.rb</a>)
     </td>
   </tr>
 
@@ -859,7 +867,7 @@ in a file, to read the content of the token from the file. (<a href="../lib/octo
       Specify the URL to the Puppet Enterprise ENC API. By default, the node classifier service
 listens on port 4433 and all endpoints are relative to the /classifier-api/ path. That means
 the likely value for this option will be something like:
-https://your-pe-console-server:4433/classifier-api (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_url.rb">pe_enc_url.rb</a>)
+https://your-pe-console-server:4433/classifier-api (<a href="../lib/octocatalog-diff/cli/options/pe_enc_url.rb">pe_enc_url.rb</a>)
     </td>
   </tr>
 
@@ -874,7 +882,7 @@ https://your-pe-console-server:4433/classifier-api (<a href="../lib/octocatalog-
     <td valign=top>
       Preserve the `environments` directory from the repository when compiling the catalog. Likely
 requires some combination of `--to-environment`, `--from-environment`, and/or `--create-symlinks`
-to work correctly. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/preserve_environments.rb">preserve_environments.rb</a>)
+to work correctly. (<a href="../lib/octocatalog-diff/cli/options/preserve_environments.rb">preserve_environments.rb</a>)
     </td>
   </tr>
 
@@ -887,7 +895,7 @@ to work correctly. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/pr
     </td>
     <td valign=top>
       Specify the API version to use for the PuppetDB. The current values supported are '3' or '4', and '4' is
-the default. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_api_version.rb">puppetdb_api_version.rb</a>)
+the default. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_api_version.rb">puppetdb_api_version.rb</a>)
     </td>
   </tr>
 
@@ -901,7 +909,7 @@ the default. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb
     <td valign=top>
       Specify the CA certificate for PuppetDB. If specified, this will enable SSL verification
 that the certificate being presented has been signed by this CA, and that the common name
-matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_ssl_ca.rb">puppetdb_ssl_ca.rb</a>)
+matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_ssl_ca.rb">puppetdb_ssl_ca.rb</a>)
     </td>
   </tr>
 
@@ -914,7 +922,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
     </td>
     <td valign=top>
       Specify the client certificate for connecting to PuppetDB. This must be specified along with
---puppetdb-ssl-client-key in order to work. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_ssl_client_cert.rb">puppetdb_ssl_client_cert.rb</a>)
+--puppetdb-ssl-client-key in order to work. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_ssl_client_cert.rb">puppetdb_ssl_client_cert.rb</a>)
     </td>
   </tr>
 
@@ -927,7 +935,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
     </td>
     <td valign=top>
       Specify the client key for connecting to PuppetDB. This must be specified along with
---puppetdb-ssl-client-cert in order to work. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_ssl_client_key.rb">puppetdb_ssl_client_key.rb</a>)
+--puppetdb-ssl-client-cert in order to work. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_ssl_client_key.rb">puppetdb_ssl_client_key.rb</a>)
     </td>
   </tr>
 
@@ -941,7 +949,7 @@ matches the name you are using to connecting. (<a href="../lib/octocatalog-diff/
     <td valign=top>
       Specify the password for a PEM or PKCS12 private key on the command line.
 Note that `--puppetdb-ssl-client-password-file` is slightly more secure because
-the text of the password won't appear in the process list. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_ssl_client_password.rb">puppetdb_ssl_client_password.rb</a>)
+the text of the password won't appear in the process list. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_ssl_client_password.rb">puppetdb_ssl_client_password.rb</a>)
     </td>
   </tr>
 
@@ -953,7 +961,7 @@ the text of the password won't appear in the process list. (<a href="../lib/octo
       Read password for SSL client key from a file
     </td>
     <td valign=top>
-      Specify the password for a PEM or PKCS12 private key, by reading it from a file. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_ssl_client_password_file.rb">puppetdb_ssl_client_password_file.rb</a>)
+      Specify the password for a PEM or PKCS12 private key, by reading it from a file. (<a href="../lib/octocatalog-diff/cli/options/puppetdb_ssl_client_password_file.rb">puppetdb_ssl_client_password_file.rb</a>)
     </td>
   </tr>
 
@@ -965,7 +973,7 @@ the text of the password won't appear in the process list. (<a href="../lib/octo
       PuppetDB base URL
     </td>
     <td valign=top>
-      Specify the base URL for PuppetDB. This will generally look like https://puppetdb.yourdomain.com:8081 (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_url.rb">puppetdb_url.rb</a>)
+      Specify the base URL for PuppetDB. This will generally look like https://puppetdb.yourdomain.com:8081 (<a href="../lib/octocatalog-diff/cli/options/puppetdb_url.rb">puppetdb_url.rb</a>)
     </td>
   </tr>
 
@@ -979,7 +987,7 @@ the text of the password won't appear in the process list. (<a href="../lib/octo
       Quiet (no status messages except errors)
     </td>
     <td valign=top>
-      Quiet option (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/quiet.rb">quiet.rb</a>)
+      Quiet option (<a href="../lib/octocatalog-diff/cli/options/quiet.rb">quiet.rb</a>)
     </td>
   </tr>
 
@@ -992,7 +1000,7 @@ the text of the password won't appear in the process list. (<a href="../lib/octo
     </td>
     <td valign=top>
       Transient errors can cause catalog compilation problems. This adds an option to retry
-a failed catalog multiple times before kicking out an error message. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/retry_failed_catalog.rb">retry_failed_catalog.rb</a>)
+a failed catalog multiple times before kicking out an error message. (<a href="../lib/octocatalog-diff/cli/options/retry_failed_catalog.rb">retry_failed_catalog.rb</a>)
     </td>
   </tr>
 
@@ -1006,7 +1014,7 @@ a failed catalog multiple times before kicking out an error message. (<a href=".
     <td valign=top>
       By specifying a directory path here, you are explicitly giving permission to the program
 to delete it if it believes it needs to be created (e.g., if the SHA has changed of the
-cached directory). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/safe_to_delete_cached_master_dir.rb">safe_to_delete_cached_master_dir.rb</a>)
+cached directory). (<a href="../lib/octocatalog-diff/cli/options/safe_to_delete_cached_master_dir.rb">safe_to_delete_cached_master_dir.rb</a>)
     </td>
   </tr>
 
@@ -1019,7 +1027,7 @@ cached directory). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/sa
       Enable integration with puppetdb for collected resources
     </td>
     <td valign=top>
-      Set storeconfigs (integration with PuppetDB for collected resources) (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/storeconfigs.rb">storeconfigs.rb</a>)
+      Set storeconfigs (integration with PuppetDB for collected resources) (<a href="../lib/octocatalog-diff/cli/options/storeconfigs.rb">storeconfigs.rb</a>)
     </td>
   </tr>
 
@@ -1034,7 +1042,8 @@ cached directory). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/sa
     <td valign=top>
       If enabled, this option will suppress changes to certain attributes of a file, if the
 file is specified to be 'absent' in the target catalog. Suppressed changes in this case
-include user, group, mode, and content, because a removed file has none of those. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/suppress_absent_file_details.rb">suppress_absent_file_details.rb</a>)
+include user, group, mode, and content, because a removed file has none of those.
+<i>This option is DEPRECATED; please use <code>--filters AbsentFile</code> instead.</i> (<a href="../lib/octocatalog-diff/cli/options/suppress_absent_file_details.rb">suppress_absent_file_details.rb</a>)
     </td>
   </tr>
 
@@ -1048,7 +1057,7 @@ include user, group, mode, and content, because a removed file has none of those
     </td>
     <td valign=top>
       Set the 'from' and 'to' branches, which is used to compile catalogs. A branch of '.' means to use
-the current contents of the base code directory without any git checkouts. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/to_from_branch.rb">to_from_branch.rb</a>)
+the current contents of the base code directory without any git checkouts. (<a href="../lib/octocatalog-diff/cli/options/to_from_branch.rb">to_from_branch.rb</a>)
     </td>
   </tr>
 
@@ -1061,7 +1070,7 @@ the current contents of the base code directory without any git checkouts. (<a h
     </td>
     <td valign=top>
       If pre-compiled catalogs are available, these can be used to short-circuit the build process.
-These files must exist and be in Puppet catalog format. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/existing_catalogs.rb">existing_catalogs.rb</a>)
+These files must exist and be in Puppet catalog format. (<a href="../lib/octocatalog-diff/cli/options/existing_catalogs.rb">existing_catalogs.rb</a>)
     </td>
   </tr>
 
@@ -1073,7 +1082,7 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
       Path to ENC script (for the to catalog only)
     </td>
     <td valign=top>
-      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/enc.rb">enc.rb</a>)
+      Path to external node classifier, relative to the base directory of the checkout. (<a href="../lib/octocatalog-diff/cli/options/enc.rb">enc.rb</a>)
     </td>
   </tr>
 
@@ -1088,8 +1097,16 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
     <td valign=top>
       Confirm that each `before`, `require`, `subscribe`, and/or `notify` points to a valid
 resource in the catalog. This value should be specified as an array of which of these
-parameters are to be checked. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/validate_references.rb">validate_references.rb</a>)
+parameters are to be checked. (<a href="../lib/octocatalog-diff/cli/options/validate_references.rb">validate_references.rb</a>)
     </td>
   </tr>
 
-</table>
+</table>
+
+## Using these options in API calls
+
+Most of these options can also be used when making calls to the [API](/doc/dev/api.md).
+
+Generally, parameters for the API are named corresponding to the names of the command line parameters, with dashes (`-`) converted to underscores (`_`). For example, the command line option `--hiera-config` is passed to the API as the symbol `:hiera_config`.
+
+Each of the options above has a link to the source file where it is declared, should you wish to review the specific parameter names and data structures that are being set.