The model
| Thing | What it is | Identified by |
|---|---|---|
| Organization | The tenant. Owns projects, members and machine identities | Chosen at sign-in |
| Project | The secrets for one codebase. Belongs to exactly one organization and has its own encryption key | A slug, such as my-app |
| Environment | One partition of a project's values | A slug: dev, staging, prod |
| Key | A secret's name, such as DATABASE_URL. Exists once per project |
The name itself |
| Value | What a key holds in one environment, with its version history | Key plus environment |
A key carries one value per environment, so DATABASE_URL in dev and DATABASE_URL in prod are two values of one key. A few settings belong to the key rather than to a value and so apply in every environment: its expiry and its proxy hosts. Changing those needs write access to the whole project.
Organizations
Every account has a personal organization and can belong to others. Members have one of three roles:
| Role | Can |
|---|---|
| Owner | Everything an admin can, plus transfer ownership and delete the organization. One per organization |
| Admin | Manage members and invitations |
| Member | Use the organization's projects, except the values of protected environments |
A CLI login acts in one organization, picked when you approve the sign-in. A project in another organization is reported as not found. To switch, enveil logout and enveil login again. Owners and admins receive the organization's emails: secrets about to expire and identities that hit their read budget.
Projects
enveil init --project my-app --create creates a project in the organization your login acts in, unless one with that slug already exists. The server derives the slug from the name you pass: lowercase ASCII letters and digits, anything else turned into a hyphen, at most 48 characters. If that slug is taken it adds a suffix (my-app-2), and init writes the slug the server returned.
enveil projects lists the projects the current credential can reach.
Environments
A new project starts with three environments:
| Name | Slug |
|---|---|
| Development | dev |
| Staging | staging |
| Production | prod |
enveil environments lists a project's environments. Commands that work on values act on one environment at a time, so a machine identity can be scoped to my-app:dev without reaching prod.
Protected environments
A protected environment keeps its values away from people with the Member role. A member can still see what is there: enveil list and enveil history work, because they fetch no values. Everything that reads a value or changes the environment is refused: get, export, run (with or without --proxy), pull, reading an old version, set, delete, rollback, and changing a key's proxy hosts or expiry. A change that spans every environment of a project, such as deleting a key everywhere, is refused as soon as one of them is protected.
| Role | In a protected environment |
|---|---|
| Owner, Admin | Read and change values, as in any other environment |
| Member | List keys and history. No values, no changes |
Production starts protected, in new projects and in projects created before protection existed. dev and staging start unprotected.
A refused call returns 403 with Production is protected: only admins can read or change its values, and the CLI exits with code 3, the same as a missing scope. enveil environments marks protected environments in a third column.
Admins and owners turn protection on or off per environment on the project's page in the dashboard. Each change is recorded in the audit log with who made it. There is no CLI command or API endpoint for it.
Protection is about people. Machine identities are not affected by it: an identity holds explicit scopes, and only an admin can mint one, so granting an identity a scope on prod is already the deliberate decision protection asks for.
Keys
Keys end up in .env files and process environments, so they are restricted to the shape a shell accepts: 1 to 255 characters, ASCII letters, digits and underscores, starting with a letter or underscore. STRIPE_SECRET_KEY and _INTERNAL are valid; stripe-key and 2FA_SECRET are not.
.enveil.toml
enveil init writes this file in the current directory:
server = "https://enveil.oxidt.com"
project = "my-app"
environment = "dev"| Field | Meaning |
|---|---|
server |
The enveil deployment |
project |
The project slug |
environment |
The environment used when -e is not given |
org |
Optional. The organization a GitHub Actions run exchanges its OIDC token into; see CI with GitHub Actions |
Commit it. It holds no secret and no token, and it is what lets everyone on the repository, and every agent, run enveil run -- … without flags.
Commands look for .enveil.toml in the current directory, then in each parent directory, and use the first one found. Running from a subdirectory of a repository, or from a package inside a monorepo, finds the file at the root.
init takes the project from --project (required), the environment from -e (default dev), and the server from --server, then ENVEIL_SERVER, then http://localhost:8080. It refuses to overwrite an existing file. enveil init --agents also appends enveil rules for coding agents to AGENTS.md and CLAUDE.md.
How a command finds its target
Every command takes -p/--project, -e/--environment and --server.
| Setting | Resolved from, first match wins | Default |
|---|---|---|
| Project | -p, then .enveil.toml |
None: the command fails and says to pass -p or run enveil init |
| Environment | -e, then .enveil.toml |
dev |
| Server | --server, then .enveil.toml, then ENVEIL_SERVER |
None: the command fails and says how to supply one |
The file sits above ENVEIL_SERVER on purpose: a project pinned to another deployment stays pointed at it, whatever is set in your shell.
When -p names a different project
With -p, no file is needed, which is what lets a command run from any directory:
enveil run -p accounts -- bunx some-mcpThat suits an MCP server launched from an unrelated repository. A .enveil.toml found there fills in the gaps only if it names the same project. If it names another project, it is ignored completely: its environment, server and org do not leak in. The environment defaults to dev and the server comes from --server or ENVEIL_SERVER:
ENVEIL_SERVER=https://enveil.oxidt.com enveil run -p accounts -e prod -- ./sync.shCommands that need no project
login, logout, projects, whoami and identity need a server but no project, so they run anywhere. They take the server from --server, then the .enveil.toml that applies, then ENVEIL_SERVER.