Write secrets into the vault
============================

Secrets in the vault are either written manually or generated by secret engines (see
:ref:`secret-engines`). ``vault-cli`` provides primitives for writing secrets manually.

.. code:: console

   $ vault-cli set a b=c
   Done
   $ vault-cli get a
   ---
   b: c

Managing several secrets in a secret object
-------------------------------------------

You can write several keys at once:

.. code:: console

   $ vault-cli set a b=c d=e
   Done
   $ vault-cli get a
   ---
   b: c
   d: e

By default, specified keys are added to the existing secret objects. If you want
to redefine a secret object from scratch, use ``--clear``:

.. code:: console

   $ vault-cli set a f=g
   Done
   $ vault-cli get a
   ---
   f: g

Write a secret from files and ``stdin``
---------------------------------------

If you assign the special value ``-`` to a secret, its value will be read from
``stdin``. You can use this when the secret has multiple lines or starts with a ``-``:

.. code:: console

   $ vault-cli set http certificate=-
   ----BEGIN SECRET KEY----
   ...
   <hit ctrl+d to end stdin>
   Done

   vault-cli get http certificate
   ----BEGIN SECRET KEY----
   ...

Identically, stream redirection and pipes allow you to write the content of a file or
the output of a program into the vault:

.. code:: console

   $ vault-cli set http certificate=- < my_certificate.key
   Done

   $ # Or:
   $ pwgen 64 1 | vault-cli set myapp secret_key=-
   Done

You can also load a several key/values in YAML (or JSON) format from a
file:

.. code:: console

   $ vault-cli set whole_secret --file=secret.yaml
   Done

Identically, the special value ``--file=-`` means that the file is read from
``stdin``.


Write a secret using an invisible input prompt
----------------------------------------------

This will avoid your secrets from being displayed in plain text in your shell
history nor on your screen.

.. note::

   This would only be useful when launched by a human, the ``stdin`` capabilities
   described above are more useful for machines.

.. code:: console

   $ vault-cli set mypath --prompt mykey
   Please enter a value for key `mykey` of `mypath`:
   Done


Write multiple secrets at once
------------------------------

Using ``vault-cli set-all`` will let you load multiple secrets from a ``yaml`` file
(or ``yaml``-encoded ``stdin`` by default). The expected format is a mapping
of secret paths and secret value objects.

.. code:: console

   $ vault-cli set-all
   ---
   a/b:
      c: d
   e:
      f: g
      h: i
   <hit ctrl+d to end stdin>
   Done
   $ vault-cli get-all
   ---
   a/b:
      c: d
   e:
      f: g
      h: i

Caveats
-------

Safe write
~~~~~~~~~~
Behaviour around overwriting secrets can be controlled, see :ref:`safe-write`.

Mixing folders and secret objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is a lingering ``vault-cli`` limitation that might disappear in the future
versions. This is just a limitation in ``vault-cli`` and not in ``vault`` as a whole.
Assuming we have a secret object at path ``a/b``:

- It's forbidden to write a secret object at ``a``
- It's forbidden to write a secret object at ``a/b/c``

In other words, a same path cannot be a secret object and a ``folder``. This reproduces
the classic file system paradigm, but not the classic URL paradigm where the notion of
``folder`` does not exist.

``vault-cli get-env --no-flat`` might have surprising results if this limitation was
to be lifted.