Secrets in scripts and CI

A secret reference names a secret without holding it. It’s safe to commit, to paste in a chat, and to keep in a .env file.

vallkey://<vault>/<item>/<field>

Each part is a name or an ID. The field is a field’s label, such as password, username or API key, or one of notes, website, title, and otp for the one-time code at that moment. If two items share a name, name the item by its ID.

Read one

vallkey read vallkey://Work/Database/password

Run a command with them

export DATABASE_PASSWORD=vallkey://Work/Database/password
vallkey run -- ./migrate

vallkey run starts the command with every reference in its environment replaced by what it names. The command gets those secrets, and never your session. Its exit code is passed on.

From a file of NAME=value lines:

vallkey run --env-file .env.vallkey -- npm start

Fill a config file

vallkey inject -i config.yml.tpl -o config.yml

Each {{ vallkey://… }} in the template is replaced, and the file is written so that only you can read it. Anything else in braces is left as it is.

In CI

Give the build a service account’s token, and the same commands work with nobody’s master password:

export VALLKEY_SERVICE_ACCOUNT_TOKEN=vlk_sa_…
vallkey run -- ./deploy.sh

What to know

• vallkey run doesn’t mask secrets in what its command prints: what the command prints, it prints.
• --password-stdin reads the master password from standard input, where a session or a service account won’t do.
• --offline skips the sync each command otherwise tries first.