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

  • run starts from the environment it was started with, then reads each --env-file in 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, %20 stands 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, run becomes the program, so no extra process stays behind holding the values, and the exit status is the program's own. On Windows, run starts the program, waits, and exits with its code.

The env file

  • One KEY=VALUE per line. The line is split at the first =, so X=a=b gives a=b.
  • Blank lines, and lines whose first character is #, are skipped. A # later in a line is part of the value: A=1 # note gives 1 # note.
  • A leading export is allowed.
  • One pair of matching quotes around the whole value ("…" or '…') is removed. There are no escapes inside quotes.
  • There is no expansion: $OTHER and ${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, run says 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.