Usage

secenv comes as a CLI, and is designed around a configuration file. It looks for (in this order):

• .secenv.yaml
• .secenv.yml

If the current directory is a Git repository, secenv can search in parent directories up to the Git root

We can split the usage of secenv in two parts, the first being configuring it, and the second being actually running the CLI.

.secenv.yaml

The configuration file of secenv is split in different parts.

We will provide a general overview of this file to understand how it works. Further details about the different sections are available in the next pages.

Stores

The first section, and maybe the most important, is about stores definition. A store is basically a bridge between the CLI and an actual secret manager.

To define a store, provide a type, and custom values specific to each store (such as an URL, credentials, etc).

In the configuration file, it looks like this (here we take the AWS Secret Manager as an example, and the local environment):

stores:
  organization_aws:
    type: aws
    region: eu-west-3
    access_key_id: AZERJF9H3H1U29ED12H9
    secret_access_key: I1920EIa912akzd0129AZd120ODAIJZ1029aoijz

  local:
    type: env

The name of the store must be unique, but the configuration file can contain multiple stores of the same type.

Secrets

Once the stores are defined, one can fill them and ensure they contain the right values. Obviously, all of this is defined as code. The second section of the configuration file contains the secrets, not their value but only their definition.

To inform secenv of the secrets to create, fill the configuration file this way:

secrets:
  - secret: DATABASE_CREDENTIALS
    store: organization_aws
    keys:
      - host
      - user
      - password
  - secret: APP_URL
    store: local

Knowing this, secenv is now able to generate (interactively) those secrets. After having run the according command (see the next section), the secret DATABASE_CREDENTIALS will be created/updated in the organization_aws store (a.k.a. AWS Secrets Manager). The secret is a key-value store, containing the keys host, user and password.

In the local environment, the variable APP_URL will be filled too.

Contexts

Last but not least, the contexts which are the main purpose of secenv. A context is not-only-but-almost a list of variables.

Contexts can extend each others, reference multiple stores, multiple secrets, retrieve just a part of a secret, and so much more that is documented in the next sections.

Here is a definition of a basic context in the configuration file:

contexts:
  default:
    vars:
      DB_HOST:
        store: organization_aws
        secret: DATABASE_CREDENTIALS
        key: host
      APP_URL:
        store: local
        secret: APP_URL

Now, generating the context default wil result in two variables being defined: DATABASE_HOST=... and APP_URL=... as provided above during the secrets definition.

secenv CLI

Now the configuration file is fully filled, one can start working with the secenv CLI to handle the secrets.

To validate the configuration file that was just created, run secenv validate.

To generate the secrets provided in the secrets section, and linked to the stores section, run secenv secrets fill. It will go through each of the secrets, and, if it exists, ask if it needs to be updated, or ask for the value if it doesn't exist yet.

Note that it's possible to fill secrets just for one store (secenv secrets fill $store) and just for one secret (secenv secrets fill $store $secret) but it's not possible yet to fill just one key.

Once the secrets exist, they can be retrieved individually by running secenv secrets get $store $secret [--key $KEY]. By example:

secenv secrets get organization_aws DATABASE_CREDENTIALS --key host
secenv secrets get local APP_URL

Those will return the values in the specified secrets. More specific options can be provided, and will be in the dedicated sections.

Once the secrets exist, and it is ensured that they are well filled, list the contexts by running secenv contexts list. It should print default.

It is now possible to generate this context by running secenv contexts gen default. Contexts can be printed following various format, typically environment values.

Now that you understand the basic usage of secenv, let's dive a bit deeper in the different components of the configuration file.