Introduction

Secrets.env is a command-line tool tailored for environment variable management. Its functionality is optimized for seamless integration with secrets management systems, such as Hashicorp Vault.

Requirements

Secrets.env requires Python 3.9+.

Installation

Install it using pipx / pip, use it as a standalone CLI tool:

pipx install secrets.env

Unlock additional functionalities by installing secrets.env with extras. Choose from several options tailored to enhance your experience:

  • all - Install everything below for comprehensive functionality.

  • keyring - Enable keyring add-on for secure credential storage.

  • teleport - Opt for the teleport add-on to streamline operations and reduce overhead when connecting through Gravitational Teleport.

  • yaml - Gain support for YAML configuration, ensuring flexibility and ease of use.

Select the extras that best suit your needs to optimize your secrets.env experience.

pipx install 'secrets.env[yaml]'

Hint

Remember to quote the extras to ensure that the shell interprets the brackets correctly.

Configuration

The configuration file is crucial, providing essential details for the tool to read credentials and securely store them.

# file: .secrets-env.toml
[[sources]]
type = "vault"
url = "https://example.com"
auth = "token"

[[secrets]]
name = "DEMO_USERNAME"
path = "secrets/default"
field = "username"

[[secrets]]
name = "DEMO_PASSWORD"
path = "secrets/default"
field = "password"

# file: .secrets-env.yaml
sources:
  - type: vault
    url: https://example.com
    auth: token

secrets:
  - name: DEMO_USERNAME
    path: secrets/default
    field: username

  - name: DEMO_PASSWORD
    path: secrets/default
    field: password

Note

YAML format is not enabled by default. See installation instructions above.

// file: .secrets-env.json
{
  "sources": [
    {
      "type": "vault",
      "url": "https://example.com",
      "auth": "token"
    }
  ],
  "secrets": [
    {
      "name": "DEMO_USERNAME",
      "path": "secrets/default",
      "field": "username"
    },
    {
      "name": "DEMO_PASSWORD",
      "path": "secrets/default",
      "field": "password"
    }
  ]
}

# file: pyproject.toml
[[tool.secrets-env.sources]]
type = "vault"
url = "https://example.com"
auth = "token"

[[tool.secrets-env.secrets]]
name = "DEMO_USERNAME"
path = "secrets/default"
field = "username"

[[tool.secrets-env.secrets]]
name = "DEMO_PASSWORD"
path = "secrets/default"
field = "password"

This configuration instructs secrets.env to retrieve two values from the Vault and assign them to DEMO_USERNAME and DEMO_PASSWORD.

Run

Secrets.env retrieves values from configured sources and assigns them as environment variables.

Once the operation is finished, the secrets are cleared from the environment to prevent exposure to other processes.

secrets.env run -- ./my-script