============
Spyglass CLI
============

The Spyglass CLI is used in conjunction with the script ``tools/spyglass.sh``.

.. note::

  The default workspace for the ``spyglass.sh`` script is ``/workspace``. The
  examples below require that this workspace be used.

CLI Options
===========

**-v / \\-\\-verbose** (Optional). False by default.

Enable debug logging.

Excel Plugin
************

Commands available under the Excel plugin package.

Generate Intermediary
---------------------

Generates an intermediary file from passed Excel data.

.. code-block:: bash

    ./spyglass.sh excel intermediary -x <engineering_excel_file> \
                    -e <excel_spec> \
                    -c <additional_site_config> \
                    -s <site_name>

Options
^^^^^^^

**-d / \\-\\-intermediary-dir** (Optional).

Path where the intermediary file will be created. Must be a writeable
directory.

**-x / \\-\\-excel-file** (Required for Excel plugin).

Path to the engineering Excel file. Multiple files can be included, provided
they follow the same specification. Must be readable file(s) in a Microsoft
Excel supported format (.xls, .xslx, etc...).

**-e / \\-\\-excel-spec** (Required for Excel plugin).

Path to the specification YAML that defines the content of the provided
engineering Excel files. Must be a readable file in YAML format.

**-c / \\-\\-site-configuration** (Optional).

Path to site specific configuration YAML. Must be a readable file.

**-r / \\-\\-rule-configuration** (Optional).

Path to rules configuration YAML file. This file defines the rules used for
data manipulation. Default rules are used if no rules YAML is entered.

**\\-\\-intermediary-schema** (Optional).

Path to the intermediary schema to be used for validation.

**\\-\\-no-validation** (Optional).

Skips validation on generated intermediary data.

**-s / \\-\\-site-name** (Optional).

Name of the site for which the intermediary is generated.

Generate Manifests
------------------

Generates manifests from intermediary file created from passed Excel data.
Intermediary data is always generated, but will not be saved unless specified.

.. code-block:: bash

    ./spyglass.sh excel documents -x <engineering_excel_file> \
                    -e <excel_spec> -c <additional_site_config> \
                    -s <site_name> -t <j2_template_directory>

Options
^^^^^^^

**-i / \\-\\-generate-intermediary** (Optional). False by default.

Saves the intermediary file used to make the manifests created by the command.

**-d / \\-\\-intermediary-dir** (Optional).

Path where the intermediary file will be created. Must be a writeable
directory.

**-x / \\-\\-excel-file** (Required for Excel plugin).

Path to the engineering Excel file. Multiple files can be included, provided
they follow the same specification. Must be readable file(s) in a Microsoft
Excel supported format (.xls, .xslx, etc...).

**-e / \\-\\-excel-spec** (Required for Excel plugin).

Path to the specification YAML that defines the content of the provided
engineering Excel files. Must be a readable file in YAML format.

**-c / \\-\\-site-configuration** (Optional).

Path to site specific configuration YAML. Must be a readable file.

**-r / \\-\\-rule-configuration** (Optional).

Path to rules configuration YAML file. This file defines the rules used for
data manipulation. Default rules are used if no rules YAML is entered.

**\\-\\-intermediary-schema** (Optional).

Path to the intermediary schema to be used for validation.

**\\-\\-no-validation** (Optional).

Skips validation on generated intermediary data.

**-s / \\-\\-site-name** (Optional).

Name of the site for which the intermediary is generated.

**-t / \\-\\-template-dir** (Required).

Path to the Jinja2 template files that will be used to generate manifest files.
Must be a readable directory with Jinja2 files using the .j2 extension.

**-m / \\-\\-manifest-dir** (Optional).

Path where generated manifest files should be written. Must be a writeable
directory.

General
*******

Generate Manifests from Intermediary
------------------------------------

Generates manifests using an existing intermediary file. This is a shortcut to
skip intermediary generation if it has already been completed.

.. code-block:: bash

    ./spyglass.sh mi <intermediary_file> -t <j2_template_directory>

Arguments
^^^^^^^^^

**INTERMEDIARY_FILE** (Required).

Path to an existing intermediary YAML file that can be used to generate
manifests.

Options
^^^^^^^

**-t / \\-\\-template-dir** (Required).

Path to the Jinja2 template files that will be used to generate manifest files.
Must be a readable directory with Jinja2 files using the .j2 extension.

**-m / \\-\\-manifest-dir** (Optional).

Path where generated manifest files should be written. Must be a writeable
directory.

**\\-\\-force** (Optional).

Forces manifests to be written, regardless of undefined data.

Validate Documents
------------------

Validates pegleg documents against their schema.

.. code-block:: bash

    spyglass validate -d <DOCUMENT_PATH> -p <SCHEMA_PATH>

Options
^^^^^^^

**-d / \\-\\-document-path**

Path to the document(s) to validate.

**-p / \\-\\-schema-path**

Path to a schema or directory of schema files used to validate documents in
document path.

Examples
========

Running Spyglass with Excel Plugin
**********************************

.. code-block:: bash

    spyglass excel documents -i -x <Excel File> -e <Excel Spec> \
               -c <Site Config> -s <Site Name> -t <j2 template dir>

Generating intermediary and manifests
-------------------------------------

.. code-block:: bash

    spyglass excel documents -i \
           -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \
           -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
           -c spyglass/examples/site_config.yaml \
           -s airship-seaworthy -t spyglass/examples/templates/

Generating intermediary without manifests
-----------------------------------------

.. code-block:: bash

    spyglass excel intermediary \
           -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \
           -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
           -c spyglass/examples/site_config.yaml \
           -s airship-seaworthy

Generating manifests without intermediary
-----------------------------------------

.. code-block:: bash

    spyglass excel documents \
           -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \
           -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
           -c spyglass/examples/site_config.yaml \
           -s airship-seaworthy -t spyglass/examples/templates/

Generating manifests using intermediary
***************************************

.. code-block:: bash

    spyglass mi <intermediary.yaml> -t <j2 template dir>

Where sample `excel_spec.yaml` and `SiteDesignSpec_v0.1.xlsx` can be found in
spyglass-plugin-xls in the `spyglass_plugin_xls/examples` folder. The Jinja2
templates and `site_config.yaml` can be found in the `spyglass/examples`
folder.

Validate Documents
******************

.. code-block:: bash

    spyglass validate -d <DOCUMENT_PATH> -p <SCHEMA_PATH>