This page describes enveil 0.3. The binary is the final word: enveil --help and enveil <command> --help print the same flags, and the exit codes at the bottom of --help.
Global flags
Every command accepts these. Most matter only to commands that talk to a project.
| Flag | What it does |
|---|---|
-e, --environment <ENV> |
Environment slug, overriding the one in .enveil.toml. |
-p, --project <PROJECT> |
Project slug, overriding the one in .enveil.toml. |
--server <URL> |
Server URL, overriding .enveil.toml and ENVEIL_SERVER. |
--json |
Print one JSON document instead of text. Honoured by list, history, projects, environments, hosts and whoami; every other command ignores it. Values are never included. |
How the target is resolved
.enveil.toml is looked for in the current directory, then every parent, so a command run from a subdirectory finds the repository's file. It is committed and holds no secrets:
server = "https://enveil.oxidt.com"
project = "acme-api"
environment = "dev"
org = "acme" # optional: only used by GitHub Actions OIDCFor a project command (list, get, run, …):
- Project:
-p, else the file'sproject. With neither, the command fails withNo .enveil.toml found. - Environment:
-e, else the file'senvironment, elsedev. - Server:
--server, else the file'sserver, elseENVEIL_SERVER.
The file only fills in what the flags left out when it names the same project. If -p names another project, the file is ignored entirely: its environment, server and org do not leak into a different repository's command. That is what lets enveil run -p accounts -- bunx some-mcp work from anywhere, as long as --server or ENVEIL_SERVER names the server.
A project's file beats ENVEIL_SERVER on purpose: a project pinned to another deployment stays pointed at it.
login, logout, projects, whoami and identity need a server but no project. They use --server, then the enclosing .enveil.toml (if it applies), then ENVEIL_SERVER, and run from any directory. init is the exception, covered below.
Environment variables
| Variable | What it does |
|---|---|
ENVEIL_SERVER |
Server URL used when neither --server nor an applicable .enveil.toml names one. Set it once (set -Ux ENVEIL_SERVER https://enveil.oxidt.com in fish) and commands work outside a project. |
ENVEIL_TOKEN |
A machine identity token (evl_…). When set and non-empty it is used instead of anything in the keychain. |
ENVEIL_ORG |
Organization slug whose trust policies an OIDC token (GitHub Actions, or ENVEIL_OIDC_TOKEN_FILE) is exchanged against. Takes precedence over org in .enveil.toml. |
ENVEIL_OIDC_TOKEN_FILE |
Path to an OIDC token to exchange, such as a Kubernetes projected service account token. A token is exchanged once: one process reuses the identity, a second process holding the same file is refused until it is rotated. |
ENVEIL_AUDIENCE |
Audience requested for the GitHub Actions OIDC token. Defaults to the server URL without a trailing slash; it must match the trust policy's audience. |
Which credential is used
ENVEIL_TOKEN, if set. The command acts as that machine identity, not as whoever logged in on the machine.ENVEIL_OIDC_TOKEN_FILE, if set: the token in that file, exchanged for an identity that lives minutes. Before the keychain because naming a file is explicit and a container often has no keychain.- The token
enveil loginstored in the OS keychain for this server. Only this one renews itself. - Inside GitHub Actions with
permissions: id-token: write: an OIDC token, exchanged for an identity that lives minutes. See CI with GitHub Actions.
With none of these the command exits 2 with No credential.
Setup
init
Write .enveil.toml in the current directory.
enveil init --project acme-api --environment dev --server https://enveil.oxidt.com
enveil init --project acme-api --create # create the project if it is missing
enveil init --project acme-api --agents # also add rules to AGENTS.md and CLAUDE.md--projectis required.--environmentdefaults todev.- The server is
--server, thenENVEIL_SERVER, thenhttp://localhost:8080. Pass one for a real deployment. --createcreates the project on the server when this credential cannot see one by that slug, so you need a credential first. Machine identities cannot create projects.--agentsappends a short block of enveil rules (run, don't read; exit code 4 is not retryable) toAGENTS.mdandCLAUDE.md, creating them if needed. A file that already has the block is left alone.- Refuses to overwrite an existing
.enveil.tomlhere.orgis never written; add it by hand if CI needs it.
login
Sign in through the browser and keep the token in the OS keychain, per server.
enveil login
enveil login --device # no local browser: SSH, a VPS, a cloud agent--device prints a code to approve in a browser on any machine. The stored login renews itself while the CLI is used; 90 days without use, or revocation, ends it and the next command exits 2 with Session expired.
logout
Revoke the stored session on the server and remove it from the keychain. If the server cannot be reached, the local token is still removed and the session expires on its own.
completions <SHELL>
Print a completion script for bash, elvish, fish, powershell or zsh.
enveil completions fish > ~/.config/fish/completions/enveil.fishReading without values
These fetch names and metadata only. They disclose nothing and cost no read budget.
| Command | What it prints |
|---|---|
projects |
Projects this credential can reach: slug and name. Runs anywhere. |
environments |
Environments of the project: slug, name, and protected on protected ones. |
list |
Key names in the environment, with allowed hosts, note and expiry date when set. A linked key shows its source as linked to project/environment:KEY. |
history KEY |
Every version of KEY: number, time, who wrote it, which one is current. |
whoami |
Who this credential is (user or machine identity), how it authenticated, organization, role, scopes, expiry and read limits. Runs anywhere; use it first when unsure what you may do. |
A project the credential has no scope for is reported as not found (exit 5), not forbidden, so slugs cannot be probed.
example
Write a .env.example with one KEY= line per key, sorted, no values. It is meant to be committed.
enveil example # keys of the current environment
enveil example --all # keys of every environment this credential can read
enveil example --force # overwrite an existing file
enveil example --out .env.template
enveil example --check # compare instead of writing--check exits 1 if a stored key is missing from the file. A key in the file that is not stored only warns: it is usually optional with a default in code. --check cannot be combined with --force. With --all, environments the credential cannot read are skipped with a warning.
Values
get KEY
Print one value to stdout with no trailing newline, so $(enveil get KEY) is exactly the secret. Every get is recorded and charged to the read budget. Prefer run.
set KEY [VALUE]
Create or replace a value. The old one is archived, not overwritten.
enveil set STRIPE_SECRET_KEY # hidden prompt
printf %s "$NEW_VALUE" | enveil set STRIPE_SECRET_KEY # from stdin
enveil set STRIPE_SECRET_KEY --expires 90d
enveil set STRIPE_SECRET_KEY --hosts api.stripe.com,files.stripe.com- Leave out
VALUE. On a terminal you get a hidden prompt; otherwise the value is read from stdin, with one trailing newline dropped. A value passed as an argument ends up in shell history and the process list. --expirestakes RFC 3339 or a span from now:30d,12w,1y. Owners are emailed a week before and once it has passed.--no-expiryclears it. An expiry belongs to the key in every environment, so both need write access to the whole project; a token scoped to one environment is refused and the value is not written either.--hosts(comma-separated) also replaces the hostsrun --proxymay send the secret to.
link KEY --from PROJECT[/ENV][:KEY]
Make KEY in this environment a link to a value in another project of the organization, usually one called shared. Reads (get, pull, run, k8s-sync) then return the source's current value, so a value several apps use is stored and rotated once. The environment and key in --from default to this environment and KEY.
enveil link SMTP_PASSWORD -p smiet -e prod --from shared # shared/prod:SMTP_PASSWORD
enveil link MAIL_PASS -p entitle -e prod --from shared/prod:SMTP_PASSWORD- Anyone who may read this environment reads the value through the link, without access to the source project. So creating a link needs an admin or owner, with a person's login (a machine identity is refused), and is recorded as
secret_linked. - If
KEYholds its own value here,linkis refused unless you pass--replace: that archives the value and creates the link in one transaction, so apullork8s-syncrunning meanwhile sees either the old value or the source's, never a missing key. A value that other links point at cannot be replaced. The source must be a value, not another link. Linking again points the link elsewhere. - While linked, the replaced value's history is out of reach.
deleteremoves the link and keeps that archive:historylists it again androllback KEY VERSIONmakes it the value again. - A linked key has no value or history of its own:
set,historyandrollbackon it are refused and name the source. Its proxy hosts, approval and expiry are the source's. - A source value that something links to cannot be deleted; the refusal lists the links. Neither can its project.
delete KEY
Delete the secret from this environment, together with its history there. On a linked key, remove the link (an admin or owner, recorded as secret_unlinked); the source is not touched.
rollback KEY VERSION
Copy an archived version forward as the new current value. The value is never decrypted for you or printed, so a bad rotation can be undone without seeing the credential. Find the version with history.
hosts KEY [HOST]...
Show or replace the hosts run --proxy may send a secret to.
enveil hosts STRIPE_SECRET_KEY api.stripe.com # replace the list
enveil hosts STRIPE_SECRET_KEY # show it
enveil hosts STRIPE_SECRET_KEY --clear # take it out of proxy mode
enveil hosts STRIPE_SECRET_KEY --approval on # a person approves each agent firstThe list lives on the server and applies in every environment of the project. Changing it needs write access to the whole project. --approval on|off sets whether a machine identity needs a person's approval, given in the web app, before the proxy injects the secret for it; list and hosts mark such a secret (approval). A machine identity cannot change it. See Proxy mode.
Running
run -- COMMAND...
Run a command with the environment's secrets in its environment. Nothing is written to disk.
enveil run -- cargo test
enveil run -e staging -- ./deploy.sh
enveil run -p accounts --server https://enveil.oxidt.com -- bunx some-mcpENVEIL_TOKENis removed from the child's environment, so the command cannot use it to fetch more.- On Linux and macOS,
enveilreplaces itself with the command: signals reach it directly, and its exit status is the one you see. - The whole environment is fetched in one export, which is recorded and charged per secret.
run --proxy -- COMMAND...
Only secrets with allowed hosts are handed to the command, and only as placeholders (__enveil_KEY_…__). A local adapter forwards HTTPS requests to those hosts through the server, which injects the real values. Other secrets are omitted, not passed in plain. The CLI downloads no values.
The adapter sets HTTPS_PROXY/HTTP_PROXY (and lowercase), extends NO_PROXY with loopback, sets NODE_USE_ENV_PROXY=1, and points SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO and DENO_CERT at a bundle with its CA. It fails if the environment has no secrets with allowed hosts. SIGTERM is forwarded to the command; a signal death exits as 128 + the signal number.
Proxy-only identities
If ENVEIL_TOKEN is a machine identity that may only use this environment through the proxy, plain run switches to --proxy by itself and says so on stderr. Nothing changes for read or write identities, or for a keychain login.
Files
pull
Write the environment to .env (or --out FILE) with mode 0600. It refuses to overwrite without --force, and warns if git does not ignore the file. Every value is disclosed and recorded; prefer run whenever the tool accepts environment variables.
push
Publish one .env file into the environment, writing only keys whose value differs.
enveil push --dry-run # which keys would be created or updated
enveil push --file .env.staging -e stagingOutput names keys, never values. Keys stored on the server but absent from the file are left alone and listed; remove one with delete. To compare, push exports the environment's current values, so even --dry-run is recorded as a read.
k8s-sync
From inside a pod, write the environment into a Kubernetes Secret in the pod's namespace, using the pod's own service account. --secret NAME is required, --restart DEPLOYMENT rolls that Deployment once per new Secret version, and --dry-run lists the keys that would change.
enveil k8s-sync -p smiet -e prod --secret smiet-env --restart smietThe Secret must already exist and ends up holding exactly the environment's keys. An empty environment is refused, nothing is written when nothing changed, output names keys only, and any failure exits non-zero with the Secret unchanged. See the repository's deploy/kubernetes/ for a CronJob and its Role.
import
Push every .env* file next to .enveil.toml into its environment: .env to the default environment, .env.<name> to the environment of that name, with production → prod, development → dev, stage → staging. .env.example, .env.sample, .env.template and .env.dist are skipped, as is any file with no matching environment. --dry-run reports what would change. See Migrating from .env files.
Identities
Both subcommands need a person's login. A machine identity asking is refused (exit 3), so an agent cannot mint itself more access. Both run anywhere.
identity create
ENVEIL_TOKEN=$(enveil identity create --name ci-deploy --scope acme-api:prod \
--capability proxy --expires 30d --budget 60/600)| Flag | Meaning |
|---|---|
--name NAME |
Required. Shown in the dashboard and audit log. |
--scope SCOPE |
Required, repeatable. project covers every environment; project:environment one. |
--capability |
Required: proxy, read or write. Prefer proxy with allowed hosts. |
--expires |
RFC 3339 or 30d, 12w, 1y. Without it the identity does not expire. |
--budget |
Read budget as per-minute/per-hour, e.g. 60/600. |
Only the token goes to stdout. The id, scopes and expiry go to stderr. See Machine identities.
identity revoke ID
Revoke an identity by id. Its token stops working at once.
Agents
skill show
Print the agent skill (SKILL.md) built into this binary, so it always matches the installed version.
skill install
Write it where an agent looks for skills. Exactly one of:
| Flag | Location |
|---|---|
--claude |
.claude/skills/enveil/SKILL.md here, or under ~ with --global |
--codex |
.agents/skills/enveil/SKILL.md here, or under ~ with --global |
--hermes |
~/.hermes/skills/enveil/SKILL.md, always under ~ |
--force overwrites an existing file. See Coding agents.
Exit codes
Branch on the code, not the message.
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Any other failure. Read the message. |
| 2 | No credential, or the session expired: run enveil login. |
| 3 | Refused (401/403): the credential lacks the scope for this, or a member's login touched values in a protected environment. |
| 4 | Read budget or rate limit exceeded: wait for the window to reset, do not retry in a loop. |
| 5 | Project, environment or secret not found. |
run exits with the command's own status. These codes mean enveil failed only when run never started the command.
Errors you will see
| Exit | Message | What to do |
|---|---|---|
| 1 | No .enveil.toml found |
Run enveil init in the repository root, or pass -p <project>. |
| 1 | pass --server, set ENVEIL_SERVER, … |
No server could be resolved. Pass --server or set ENVEIL_SERVER. |
| 2 | No credential |
Run enveil login, or set ENVEIL_TOKEN. |
| 2 | Session expired |
The login went 90 days unused or was revoked. Run enveil login. |
| 1 | Could not renew the session right now |
Rate limit or server trouble while renewing; the login is kept. Try again later. |
| 5 | Project or secret not found | Also what a project without a scope looks like. Check enveil projects. |
| 4 | Read budget exceeded | Reading too fast. Stop; the budget resets with its window. |
| 3 | 401 / 403 | The credential lacks the scope for that environment. Check enveil whoami. |
| 3 | … is protected: only admins can read or change its values |
Your role is Member and the environment is protected. Ask an admin, or use a machine identity scoped to it. |
| 1 | No proxied secrets in … |
run --proxy found no secret with allowed hosts. Set some with enveil hosts. |