Concepts
This page explains the model behind the CLI. Open the concepts overview
Contract¶
The contract is the shared definition of what the project environment requires. It is the repository-owned layer of the model: names, requirements, safe defaults, and structure — not one machine’s actual values.
What it is¶
A contract answers one question:
What does this project expect to exist in its environment?
That makes it shared intent, not local truth.
Why it matters¶
Without a contract, environment handling drifts into habit:
- copy someone else’s file
- tweak it locally
- hope CI matches
- repeat the same onboarding explanation later
The contract stops that by making requirements explicit, reviewable, and versioned.
If the team can discuss it, review it, and commit it safely, it probably belongs in the contract.
What problem it solves¶
The contract gives the team one stable place to answer:
- which variables matter
- which ones are required
- what shape the environment has
- what should be validated before runtime
That is why contract changes belong in Git:
$ envctl add API_KEY
$ git add .envctl.yaml
$ git commit -m "require API_KEY"That commit changes project requirements. It does not distribute anyone’s real secret.
What it is not¶
The contract is not the place for:
- developer-specific secrets
- personal machine URLs or credentials
- copied dotenv files
- generated projection artifacts
- anything that turns the repository into a secret transport layer
Those belong to local storage, not to the shared model.
How it fits in the system¶
The contract is the first layer in the chain:
- the contract defines requirements
- the vault stores local values
- profiles select one local context
- resolution computes what is true for this run
- projection hands that result to the runtime
Validation makes the contract operational: envctl check asks whether the currently resolved local environment satisfies the shared contract.
Read next¶
Profiles¶
See how the same contract can be satisfied through different local contexts.