Command Line Usage
==================

General options
---------------

.. code-block:: console

  usage: batou [-h] [-d] {deploy,secrets,init} ...

  batou v2.0b12: multi-(host|component|environment|version|platform) deployment

  positional arguments:
    {deploy,secrets,init}
      deploy              Deploy an environment.
      secrets             Manage encrypted secret files. Relies on age (or GPG)
                          being installed and configured correctly.
      migrate             Migrate the configuration to be compatible with the
                          batou version used. Requires to commit the changes
                          afterwards. Might show some additional upgrade steps
                          which cannot be performed automatically.

  optional arguments:
    -h, --help            show this help message and exit
    -d, --debug           Enable debug mode. (default: False)


batou deploy
------------

.. code-block:: console

  usage: batou deploy [-h] [-p PLATFORM] [-t TIMEOUT] [-D] [-c] [-P]
                      [--local] [-j JOBS]
                      [--provision-rebuild]
                      environment

  positional arguments:
    environment           Environment to deploy.

  optional arguments:
    -h, --help            show this help message and exit
    -p PLATFORM, --platform PLATFORM
                          Alternative platform to choose. Empty for no platform.
    -t TIMEOUT, --timeout TIMEOUT
                          Override the environment's timeout setting
    -D, --dirty           Allow deploying with dirty working copy or outgoing
                          changes.
    -c, --consistency-only
                          Only perform a deployment model and environment
                          consistency check. Only connects to a single host.
                          Does not touch anything.
    -P, --predict-only    Only predict what updates would happen. Do not change
                          anything.
    -L, --local           When running in consistency-only or predict-only mode,
                          do not connect to the remote host, but check and
                          predict using the local host's state.
    -j JOBS, --jobs JOBS  Defines number of jobs running parallel to deploy. The
                          default results in a serial deployment of components.
                          Will override the environment settings for operational
                          flexibility.
    --provision-rebuild   Rebuild provisioned resources from scratch. DANGER:
                          this is potentially destructive.

batou secrets edit
------------------

.. code-block:: console

    usage: batou secrets edit [-h] [--editor EDITOR] environment

    positional arguments:
      environment           Environment to edit secrets for.

    optional arguments:
      -h, --help            show this help message and exit
      --editor EDITOR, -e EDITOR
                            Invoke EDITOR to edit (default: $EDITOR or vi)

batou secrets summary
---------------------

Show an overview of which users have access to what encrypted secrets.

.. code-block:: console

    usage: ./batou secrets summary [-h]

    optional arguments:
      -h, --help  show this help message and exit

Example:

.. code-block:: console

    $ ./batou secrets summary

    production
      members
        - alice@example.com
      secret files
        - secrets.yaml

    tutorial
      members
        - alice@example.com
        - bob@example.com
      secret files
        (none)


batou secrets add
-----------------

.. code-block:: console

    usage: batou secrets add [-h] [--environments ENVIRONMENTS] keyid

    positional arguments:
      keyid                 The user's key ID or email address

    optional arguments:
      -h, --help            show this help message and exit
      --environments ENVIRONMENTS
                            The environments to update. Update all if not
                            specified.

batou secrets remove
--------------------

.. code-block:: console

    usage: batou secrets remove [-h] [--environments ENVIRONMENTS] keyid

    positional arguments:
      keyid                 The user's key ID or email address

    optional arguments:
      -h, --help            show this help message and exit
      --environments ENVIRONMENTS
                            The environments to update. Update all if not
                            specified.

batou secrets reencrypt
-----------------------

Re-encrypt all secrets with the current set of keys. This is useful when
you want to update the set of public keys fetched from a key server.

.. code-block:: console

    usage: batou secrets reencrypt [-h] [--environments ENVIRONMENTS]

    optional arguments:
      -h, --help            show this help message and exit
      --environments ENVIRONMENTS
                            The environments to update. Update all if not
                            specified.

batou secrets decrypttostdout
-----------------------------

Decrypts a secret file to stdout.
It's intended usage is for allowing git to decrypt secrets before displaying a diff to the user.
You can set up the command withing your project like this:

.. code-block:: console

    git config diff.batou.textconv "./batou secrets decrypttostdout"
    echo "*.gpg diff=batou" >> .gitattributes
    echo "*.age diff=batou" >> .gitattributes
    echo "*.age-diffable diff=batou" >> .gitattributes

This only works if your batou binary is in the root of your git project.
.. code-block:: console

    usage: batou secrets decrypttostdout [-h] file

    positional arguments:
      file        The secret file to decrypt, should be contained in an
                  environment.

    optional arguments:
      -h, --help  show this help message and exit