Run

The run command runs a program and passes secret environment variables to it:

secrethub run [options] -- <command>

Anything that goes after the double dashes -- is the command you want to run.

Environment variables are passed to the executed process with the following order of precedence, ranking the most important method first:

1. The --envar NAME=PATH flag, e.g. --envar DB_PASSWORD=path/to/secret
2. Environment variables configured with the secret reference syntax (secrethub://path/to/secret)
3. .env files. By default secrethub.env is used; Use the --env-file flag to use a different file.
4. Environment variables passed to the run command by the OS. They don’t have to be related to SecretHub.

Environment Files

Environment Files allow you to codify multiple (secret) environment variables with KEY=VALUE statements separated by a newline. These files have the .env extension and their default name is secrethub.env.

You can both define static values and use template syntax to inject secrets at runtime. You can even use variable tags to control which secrets get injected, e.g. to differentiate between environments with the variable $env:

$ cat secrethub.env
# Static values
DB_HOST     = localhost:5432
# Secrets
DB_USER     = {{ company/repo/$env/db/user }}
DB_PASSWORD = {{ company/repo/$env/db/password }}

$ secrethub run --var env=dev --no-masking -- printenv | grep DB
DB_HOST=localhost:5432
DB_USER=db-user-dev-1
DB_PASSWORD=75KNf88DZ9zFN5V7ktRoTt

$ secrethub run --var env=prd --no-masking -- printenv | grep DB
DB_HOST=localhost:5432
DB_USER=db-user-prd-1
DB_PASSWORD=W0sJWq9OIipoqC6TvzreRD

Read more about the template syntax here.

Note the difference between a variable and an environment variable, the former being a value you pass to the template and the latter being a value you pass to the running process.

Environment File syntax rules

The .env file parsing engine currently supports the following rules:

• Environment variables are defined with as KEY=VALUE statements separated by a newline. Statements themselves cannot contain a newline.
• Empty lines are skipped.
• Lines beginning with # are treated as comments. Comments cannot be placed inline after KEY=VALUE statements.
• Empty values become empty strings, so EMPTY= will set the environment variable EMPTY to the empty string.
• Single and double quoted values are escaped, so KEY="VALUE" and KEY='VALUE' both evaluate to KEY and VALUE
• Inner quotes are maintained, so JSON={"foo":"bar"} evaluates to JSON and {"foo":"bar"}.
• Template syntax can be used in the VALUE to inject secrets. The KEY can only contain template variables.
• Template parsing is performed after .env file parsing, so you cannot use the former to construct the latter.
• Leading and trailing whitespace of both KEY and VALUE segments is ignored, so KEY = VALUE is parsed the same as KEY=VALUE.
• Single and double quoted values maintain whitespace from both ends, so KEY=" some value " evaluates to KEY and ` some value `.

These files should use UTF-8 character encoding.

Migrating from YAML Environment Files

.yml environment template files have been deprecated and will be removed in a future CLI version. We recommend migrating your templates to the .env file syntax.

To migrate your .yml env files to .env, simply replace the colons : with an equal sign =.

Secret References (secrethub://)

Secret references can be used to inject secrets without the need of creating (or editing) the environment file.

Any environment variable value of the form secrethub://path/to/secret will be replaced with the specified secret.

Masking

By default, secrets passed to the child process are filtered from the stdout and stderr streams of the child process. Any secret value that is detected, is replaced by <redacted by SecretHub>. This avoids secrets ending up in log files.

Note that masking will only be performed for secret values that are UTF-8 encoded in the output streams.

As demonstrated in the examples above, masking can be disabled with the --no-masking flag.

Security benefits of using the run command

There are common security concerns surrounding storing secrets as environment variables:

• Environment variables are often set globally, inadvertently exposing them to processes that don’t need them.
• Environment variables can be inspected with tools like kubectl describe, aws ecs describe-task-definition or docker inspect, exposing plaintext secrets.
• Applications often print the whole environment, exposing any secret environment variables provided to them.

By injecting secrets at runtime and masking them in logs, the run command prevents secrets being leaked through shell wide environment variables, runtime inspection tools and/or log files.

Arguments

[<command>] (string)

The command you want to run. This can be any command you would normally type into the command-line.

Flags

-e, --envar (string)

Source an environment variable from a secret at a given path with NAME=<path>. You can use multiple flags to set multiple variables.

--env-file (string)

The path to an Environment File with environment variable mappings of the form NAME=value separated by newlines. Templates are automatically injected with secrets when passed to the run command. This allows you to define both hardcoded values and source values from SecretHub. If the file secrethub.env exists in the current directory, it is used as the default.

--template-version (string)

The template syntax version to be used. The options are v1, v2, latest or auto to automatically detect the version. Defaults to auto.

-v, --var (string)

Define the value for a template variable with VAR=VALUE, e.g. --var env=prd You can use multiple flags to set multiple variables.

--no-prompt (boolean)

Disables prompting the user for missing template variables.

--secrets-dir (string) new in v0.41.0

Recursively load all secrets from a directory into environment variables. Names of the environment variables are derived from the path of the secret: all / are replaced with _ and the name is uppercased.

For example, if you provide the directory acme/my-application/dev, which has the following tree:

acme/my-application/dev/
 ├── aws/
 │   ├── access_key_id
 │   └── secret_access_key
 └── stripe_secret_key

If you run the following command:

secrethub run --secrets-dir acme/my-application/dev -- ./my-application

The following environment variables will be passed to ./my-application:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
STRIPE_SECRET_KEY=sk_test_51CYDvqCV0IwKcbmMHubzOdaTXm4xsgX

--ignore-missing-secrets (boolean)

If set, the command will not error when a secret is not found. Missing secrets will have the value of "".

--no-masking (boolean)

Disables masking of secret values from stdout and stderr.

--no-output-buffering (boolean)

Disable output buffering. This increases output responsiveness, but decreases the probability that secrets get masked.

--masking-buffer-period (duration, e.g. 2s or 10ms)

The time period for which output is buffered. A higher value increases the probability that secrets get masked but decreases output responsiveness.