envref
A .env where any value can be a reference into a secret store, resolved
when the file is loaded.
# .env
ATTIO_KEY={{ op://work/Attio/api_key }} # 1Password
DB_PASSWORD={{ keychain://myapp/postgres }} # macOS Keychain
TLS_KEY={{ file://~/.ssh/server.pem }} # a file's contents
GITHUB_TOKEN={{ env://GH_TOKEN }} # another variable
REGION=eu-north-1 # a plain literal
envref run -- python app.py # app.py sees ATTIO_KEY=<the real key>
import envref
envref.load(".env") # same thing, into os.environ
The file holds no secrets, so it can be committed. The scheme of each reference picks the backend. Four ship built in, and your own takes one class and one entry point.
Why
op run, berglas exec, chamber exec and friends each do this for one
store. Teams rarely have one store. A laptop has 1Password and Keychain, a
container has a service account, a CI job has its own vault, and the same
.env should work in all three with the same names. envref keeps the file
format (plain dotenv, plus {{ scheme://… }}), and makes the backend a plugin.
Install
uv tool install envref # CLI
pip install envref # library, zero dependencies
pip install 'envref[op]' # + 1Password service-account support (SDK)
The op:// CLI path needs only the op
binary on PATH, no extra.
Resolvers
| Scheme | Resolves to | Needs |
|---|---|---|
op://vault/item/field |
a 1Password field | op CLI, or OP_SERVICE_ACCOUNT_TOKEN + envref[op] |
keychain://service/account |
a macOS Keychain generic password | macOS |
file://path |
the file's contents, one trailing newline dropped | — |
env://NAME |
another environment variable | — |
A value written as {{ scheme://… }} is always a reference, and an unknown
scheme is an error. A bare scheme://… without braces is resolved only when a
resolver for that scheme is installed, so URL=https://example.com stays a
literal and KEY=op://vault/item/field still works for files written for
op read.
1Password in detail
Two modes, chosen by the environment:
- Service account when
OP_SERVICE_ACCOUNT_TOKENis set. The SDK resolves every reference in one round trip. No binary, no biometrics. For containers. - CLI otherwise. Every reference goes through one
op inject. Ifophas no session,envrefsigns in: the account password comes from Keychain behind Touch ID if you stored it withenvref op save-password, or from the terminal if not. The session token is cached in~/.cache/envref/so a burst of commands costs one sign-in; concurrent processes share it through a lock. See SECURITY.md for what that cache means.
Session caching presumes "biometric unlock for the CLI" is off in the
1Password app. With it on, op prompts per invocation and envref holds no
token.
Knobs: OP_ACCOUNT (shorthand, when several accounts are signed in),
ENVREF_OP_SESSION_TTL (seconds, default 1500, 0 disables the cache),
ENVREF_OP_KEYCHAIN_SERVICE / ENVREF_OP_KEYCHAIN_ACCOUNT (where the
password is stored, default envref-op / the account's email).
CLI
envref run [-f FILE]... [--override] -- cmd args # exec cmd with the resolved environment
envref export [-f FILE]... [--format shell|dotenv|json]
envref check [-f FILE]... # resolve and report per key; never prints a value
envref doctor # installed resolvers and whether each can run here
envref op save-password [--account SHORTHAND] # store the 1Password password in Keychain for Touch ID sign-in
-f repeats. The first file to set a name wins, so -f .env.refs -f .env
lets a local .env fill in what the shared references file lacks without
overriding it. Default is .env.
Library
import envref
values = envref.load(".env.refs", ".env") # dict, also exported into os.environ
values = envref.load(".env", export=False) # dict only
envref.load(".env", override=True) # let the file win over existing variables
entries = envref.parse(text) # list[Entry], refs identified
envref.resolve(entries, registry={"op": ...}) # bring your own resolvers
Errors are typed: UnknownScheme, ResolverUnavailable (the backend cannot
run here: no op, not macOS, no token) and ResolveError (which references
failed and why, in .failures). All derive from EnvrefError.
Writing a resolver
# myenvref/aws.py
class SecretsManagerResolver:
scheme = "awssm"
def resolve(self, refs: list[str]) -> dict[str, str]:
# refs are every awssm:// reference in the file, deduplicated: batch them.
...
return {ref: value for ref, value in ...}
def doctor(self) -> str: # optional, shown by `envref doctor`
return "ok"
# pyproject.toml
[project.entry-points."envref.resolvers"]
awssm = "myenvref.aws:SecretsManagerResolver"
Installed next to envref, {{ awssm://… }} now resolves. An entry point
with a built-in's name replaces it.
Prior art
teller and
novops are multi-provider too,
with the mapping in a YAML config rather than inline in the .env.
berglas has inline
sm:// references, for Google Cloud only. dotenvx
encrypts the values rather than referencing them. op inject is what the
{{ }} syntax comes from, and any .env.op written for it is a valid
envref file.
Status
Extracted in November 2026 from a private automation repository where the 1Password path had run daily for a year, on a laptop and in scheduled containers. The other resolvers are new. macOS and Linux; Keychain and Touch ID are macOS only.
MIT.
Metadata
Release files for envref 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| envref-0.1.0.tar.gz | 22.2 kB | Without provenance | Details for envref-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| envref-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for envref-0.1.0-py3-none-any.whl |
Total release size: 43.9 kB
Release files / envref-0.1.0.tar.gz
| Download URL | envref-0.1.0.tar.gz |
|---|---|
| Size | 22.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b5f1f6520ef57b6e1664bcc505277e6b9daf6e4c7feb51ad2b566d96cc869f56
|
|
BLAKE2b-256 checksum How to use checksums |
b4efa1b8a8bd0c48539ca608433a3ef3895e13dcdb9fae3a6cd58c3a38455470
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Release files / envref-0.1.0-py3-none-any.whl
| Download URL | envref-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
446aeaed2b1233d9c6036a1bec5533c1f239f95445299cead080f97ac39cba5c
|
|
BLAKE2b-256 checksum How to use checksums |
b74ba6d1159fcd291905d212ea7868829f687755170f591c7804ab1739ce3d73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Security for envref 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.