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:
- The
--envar NAME=PATH
flag, e.g.--envar DB_PASSWORD=path/to/secret
- Environment variables configured with the secret reference syntax (
secrethub://path/to/secret
) -
.env
files. By defaultsecrethub.env
is used; Use the--env-file
flag to use a different file. - 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 afterKEY=VALUE
statements. - Empty values become empty strings, so
EMPTY=
will set the environment variableEMPTY
to the empty string. - Single and double quoted values are escaped, so
KEY="VALUE"
andKEY='VALUE'
both evaluate toKEY
andVALUE
- Inner quotes are maintained, so
JSON={"foo":"bar"}
evaluates toJSON
and{"foo":"bar"}
. - Template syntax can be used in the
VALUE
to inject secrets. TheKEY
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
andVALUE
segments is ignored, soKEY = VALUE
is parsed the same asKEY=VALUE
. - Single and double quoted values maintain whitespace from both ends, so
KEY=" some value "
evaluates toKEY
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
ordocker 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 therun
command. This allows you to define both hardcoded values and source values from SecretHub. If the filesecrethub.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
orauto
to automatically detect the version. Defaults toauto
. -
-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
andstderr
. -
--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
or10ms
) - The time period for which output is buffered. A higher value increases the probability that secrets get masked but decreases output responsiveness.