========
Tutorial
========


In this tutorial you will encrypt a secret file into a git-safe vault and
restore it on a fresh clone. Here is the end result:

.. code:: text

    $ nimvault status
    ------------------------------------------------------------------------
      Vault status
    ------------------------------------------------------------------------
      [in-sync]   ~/.config/myapp/secrets.env

Your secrets are now committed as opaque GPG blobs. Clone on another machine,
run ``nimvault unseal``, and the plaintext files reappear.

Install nimvault
----------------

.. code:: bash

    # Requires Nim >= 2.0
    nimble install nimvault

Verify:

.. code:: bash

    nimvault --version
    # nimvault 0.5.3

Set up a test repo
------------------

.. code:: bash

    # Create a throwaway repo to practice with
    mkdir /tmp/vault-demo && cd /tmp/vault-demo
    git init

Create a secret file
--------------------

.. code:: bash

    # This file will be encrypted into the vault
    mkdir -p ~/.config/myapp
    echo "DB_PASSWORD=hunter2" > ~/.config/myapp/secrets.env

Configure the vault recipient
-----------------------------

.. code:: bash

    # Find your GPG key ID
    gpg --list-keys --keyid-format long
    # pub   rsa4096/9CCCE36402CB49A6 2024-01-01 [SC]
    #                ^^^^^^^^^^^^^^^^ copy this

    # Tell nimvault which key to encrypt to
    mkdir -p .vault
    echo "recipient = 9CCCE36402CB49A6" > .vault/config
    # ^ replace with YOUR key ID

Add the file to the vault
-------------------------

.. code:: bash

    nimvault add ~/.config/myapp/secrets.env
    # Added:
    #   id:   7f3a2b1c9e4d8f06
    #   path: ~/.config/myapp/secrets.env
    #   blob: .vault/7f3a2b1c9e4d8f06.gpg

The file path is stored with ``~/`` so it works on any machine. The ID is a
random 16-char hex string.

Seal the vault
--------------

.. code:: bash

    nimvault seal
    # Encrypting ~/.config/myapp/secrets.env
    # Sealed 1 file(s).

Commit
------

.. code:: bash

    git add .vault/
    git commit -m "vault: add myapp secrets"

Only encrypted material is committed: the blobs, the signed manifest, and the
data-key file that lets a second machine be added without re-encrypting
everything. The original filename (``secrets.env``) never appears in git history.

Check status
------------

.. code:: bash

    nimvault status
    # [in-sync]   ~/.config/myapp/secrets.env

``status`` compares the plaintext on this machine against the manifest. To check
the vault itself is intact -- every blob still matching the digest recorded for
it -- use ``check``, which decrypts nothing and needs no key:

.. code:: bash

    nimvault check
    # 1 entries consistent with the manifest.

Simulate a fresh checkout
-------------------------

.. code:: bash

    # Delete the plaintext to simulate a new machine
    rm ~/.config/myapp/secrets.env

    nimvault status
    # [missing]   ~/.config/myapp/secrets.env

    # Restore from the vault
    nimvault unseal
    # Unsealing ~/.config/myapp/secrets.env
    # Unsealed 1 file(s).

    # Verify the file is back (permissions: 600)
    cat ~/.config/myapp/secrets.env
    # DB_PASSWORD=hunter2

    ls -la ~/.config/myapp/secrets.env
    # -rw------- 1 user user ... secrets.env

Clean up
--------

.. code:: bash

    # Remove the demo repo and test file
    rm -rf /tmp/vault-demo
    rm ~/.config/myapp/secrets.env
    rmdir ~/.config/myapp 2>/dev/null

Next steps
----------

- `Encrypting directories <tutorials/directory-support.rst>`_ -- add entire directories with ``add-dir``

- `chezmoi integration <howto/chezmoi.rst>`_ -- use nimvault to encrypt dotfiles secrets

- `CLI reference <reference/cli.rst>`_ -- all commands and flags

- `Configuration <reference/config.rst>`_ -- recipient resolution chain

- `Manifest format <reference/manifest.rst>`_ -- how the encrypted index works