Documentation / Reference / CLI / Commands / run

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. Environment variables configured on the command-line with the --envar KEY=PATH flag, e.g. --envar DB_PASSWORD=path/to/secret
  2. Environment variables configured in a .env file. By default secrethub.env is used; Use the --env-file flag to use a different file.
  3. Environment variables defined in the environment passed to the run command by the OS.

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 =.

Masking

By default, all 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.

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-masking (boolean)
Disables masking of secret values from stdout and stderr.
--masking-timeout (duration, e.g. 2s or 10ms)
The time to wait for the write of a secret that is partially written to stdout or stderr to be completed. If the secret is completely written to any of these streams within the timeout, it is masked. Otherwise the partial secret is written anyway. Default value is 1s.