The CLI / wolpass run

wolpass run

Run a command with entries as environment variables, for that command and nothing else.

SYNOPSIS

wolpass run -e PATH [-e PATH]... [flags] -- COMMAND [ARG]...
wolpass run --map NAME=PATH[:FIELD]... [flags] -- COMMAND [ARG]...

What it does

It opens the entries you name, puts their values in the environment of COMMAND, and runs it. When COMMAND exits, the values go with it. Nothing is written to disk, and wolpass prints no value.

Name a folder and each entry directly in it becomes a variable with the entry's name: saltmarsh/infra/ci/REGISTRY_TOKEN becomes REGISTRY_TOKEN. Subfolders are left out. To choose a name or a field, use --map.

With your YubiKey, you touch it once for the whole run, however many entries it opens. With a machine key in WOLPASS_MACHINE_KEY, there is no touch at all. That is the trade-off of a machine key, and each run is in the workspace's audit log.

Flags

FLAG	WHAT IT DOES
-e, --entry PATH	An entry or a folder to open. Repeat it for more.
--map NAME=PATH[:FIELD]	Put one field of one entry in `NAME`. The field is the password unless you name another: `login`, `url`, `otp`, or any field the entry has.
--only NAME	From a folder, set only this variable. Repeat it for more. The rest stay sealed.
--clean-env	Start `COMMAND` with only what wolpass sets, plus `PATH`, `HOME` and `LANG`.
--dry-run	Print which names would be set, and from which entries. Opens nothing and asks for no touch.
--ws NAME	Read paths in this workspace. `--ws saltmarsh -e infra/ci` is the same as `-e saltmarsh/infra/ci`.
-q	Print nothing of wolpass's own, so only `COMMAND` speaks.

WOLPASS_MACHINE_KEYThe private half of a machine key. When it is set, wolpass run opens with it instead of your YubiKey, and takes it out of COMMAND's environment.

Examples

Deploy from your laptop, with a folder of CI secrets

$ wolpass run -e saltmarsh/infra/ci -- make deploy
touch once for 4 entries · touched
set for make, and nothing else:
  AWS_ACCESS_KEY_ID  AWS_SECRET_ACCESS_KEY  REGISTRY_TOKEN  SENTRY_DSN
make: building atlas [VERSION]
make exited 0 · the 4 values went with it

One field, under the name a program expects

$ wolpass run --map FIELDNOTE_TOKEN=web/fieldnote:api-token -- ./sync-notes

In CI, with a machine key

# WOLPASS_MACHINE_KEY is in the CI's secret store, pasted once
# when atlas-ci was made. It can read saltmarsh/infra/ci/ only.
$ wolpass run -e saltmarsh/infra/ci -- make deploy
machine key atlas-ci · read 4 entries · logged

See what would be set, without opening anything

$ wolpass run --dry-run -e saltmarsh/infra/ci --only REGISTRY_TOKEN -- make push
would set  REGISTRY_TOKEN  from saltmarsh/infra/ci/REGISTRY_TOKEN
nothing opened

What reaches the command

IT GETS

The variables you named

Your own environment, unless you add --clean-env

The same, for every process it starts

IT DOES NOT GET

WOLPASS_MACHINE_KEY, or your PIN

Entries you did not name

A file with the values in it

After that, it is the command's to keep

If it prints its environment, or a tool logs it, the value is in your terminal or your CI log. While it runs, other programs running as the same user can read its environment. Name only what the command needs.

When it ends

wolpass run exits with COMMAND's status. If an entry cannot be opened, COMMAND does not start, and wolpass says which entry and why: no touch, wrong key, or not sealed to you yet.