Command Line Interface
======================

Sceptre can be used as a command line tool.
Running Sceptre without a sub-command will display help, showing a list of the
available commands.

Autocomplete
------------

To enable CLI autocomplete for subcommands and parameters execute the
following command:

+----------+-------------------------------------------------+
| shell    | command                                         |
+==========+=================================================+
| bash     | eval "$(_SCEPTRE_COMPLETE=source_bash sceptre)" |
+----------+-------------------------------------------------+
| zsh      | eval "$(_SCEPTRE_COMPLETE=source_zsh sceptre)"  |
+----------+-------------------------------------------------+

Export Stack Outputs to Environment Variables
---------------------------------------------

Stack outputs can be exported as environment variables with the command:

``eval $(sceptre --ignore-dependencies list outputs STACKGROUP/STACK.yaml --export=envvar)``

Note that Sceptre prepends the string ``SCEPTRE_`` to the name of the
environment variable:

.. code-block:: text

   env | grep SCEPTRE
   SCEPTRE_<output_name>=<output_value>

Variable Handling
-----------------

You can pass variables into your project using ``--var-file`` and ``--var``.

Variables passed in with ``--var`` will overwrite any matching variables specified in
``--var-file``. If you use multiple ``--var`` flags then the right-most ``--var`` will
overwrite any matching ``--vars`` to the left. For example, in the following command

``sceptre --var var1=one --var var2=two --var var1=three launch stack``

``var1`` will equal ``three``.

You can also use ``--var`` to overwrite nested keys in a ``--var-file``. For example,
given a variable file "vars.yaml":

.. code-block:: yaml

  # vars.yaml
  ---
  top:
    middle:
      nested: hello
    middle2:
      nested: world

we could overwrite ``nested: world`` to ``nested: hi`` using:

``sceptre --var-file vars.yaml --var top.middle2.nested=hi launch stack``

.. note::
  Sceptre will load your entire project to build a full dependency graph.
  This means that all stacks that use variables will need to have a value
  provided to them - even if they are not in your ``command_path`` or are not
  a dependency. Using a --var-file with all variables set can help meet this
  requirement.

It is also possible to have keys merged according to a deep merge
algorithm from successive var files, by specifying ``--merge-vars``. So, if we
had a second variable file "vars2.yaml":

.. code-block:: yaml

  # other_vars.yaml
  ---
  top:
    middle3:
      nested: more world


We could merge all of this together using:

``sceptre --merge-vars --var-file vars.yaml --var-file other_vars.yaml launch stack``

The ``top`` dictionary would then be expected to contain:

.. code-block:: python

  {
    "top": {
      "middle": {"nested": "hello"},
      "middle2": {"nested": "world"},
      "middle3": {"nested": "more world"}
    }
  }

Command reference
-----------------

Command options differ depending on the command, and can be found by running:

.. code-block:: text

   sceptre
   sceptre --help
   sceptre COMMAND --help


.. click:: sceptre.cli:cli
  :prog: sceptre
  :show-nested: