clavitor-cli run
run starts a program with its secrets in its environment, so your real keys no longer have to sit in a .env file. The file holds a pointer, and the key comes from your vault as the program starts.
Before and after
A .env file with the real key, the way it is today:
STRIPE_KEY=sk_live_51H...
The same file with a pointer:
STRIPE_KEY=clavitor://Stripe/key
Start your app with run instead of starting it directly:
clavitor-cli run --env-file .env -- ./server
The app gets the real key from your vault. The file, your shell and your history only ever see the pointer.
Usage
clavitor-cli run [--env-file <file>]... -- <command> [arguments...]
Everything after -- is the program and its arguments. You can also name a reference in the environment directly, without a file:
STRIPE_KEY=clavitor://Stripe/key clavitor-cli run -- node app.js
How it works
runstarts from the environment it was started with, then reads each--env-filein the order given. A file's variable replaces the same name from the environment, a later file beats an earlier one, and within a file a later line beats an earlier one.- Every variable is checked, the inherited ones included. A value can hold several references.
- References are resolved exactly as render resolves them: the title must match one entry exactly,
%20stands for a space, the field is the part after the last/, and a reference ends at a space, quote, comma or}. - The program gets that whole environment, with the references filled in, and nothing else.
- On Linux and macOS,
runbecomes the program, so no extra process stays behind holding the values, and the exit status is the program's own. On Windows,runstarts the program, waits, and exits with its code.
The env file
- One
KEY=VALUEper line. The line is split at the first=, soX=a=bgivesa=b. - Blank lines, and lines whose first character is
#, are skipped. A#later in a line is part of the value:A=1 # notegives1 # note. - A leading
exportis allowed. - One pair of matching quotes around the whole value (
"…"or'…') is removed. There are no escapes inside quotes. - There is no expansion:
$OTHERand${OTHER}stay as written. - A line without
=, or a name with anything other than letters, digits and_, stops the run with the file and line number. A reference that fails names its variable, for example$STRIPE_KEY: ….
All or nothing
If one reference can't be found, matches more than one entry or fails to decrypt, the program is not started, so it never runs half set up. With no references at all, run never contacts the vault.
- At most 10 distinct entries per run, and 128 references over all variables together, the same caps as
render. - Fields under Identity Encryption are refused: an agent can't open them.
- Each distinct entry counts once against the client's read quota, and every read is in the vault's audit log. On stderr,
runsays how many fields it filled in.
Where the values end up
run prints nothing to stdout and writes nothing to disk or to the command line. Once the program has started, the values are in its environment, and the program, every process it starts and anyone who can read its /proc entry can read them. Where your app can read a config file instead, render piped straight into it keeps the secrets out of the environment, which makes it the better fit there.