Concepts
This page explains the model behind the CLI. Open the concepts overview
Profiles¶
Profiles let one machine hold more than one local value set for the same contract. They exist so you can switch local context without rewriting shared requirements or mutating one single local state over and over.
What they are¶
A profile answers this question:
Which local value set should this machine use right now?
It is a local context selector, not another project definition.
Why they matter¶
Without profiles, people usually end up:
- overwriting values in place
- renaming files manually
- keeping several ad-hoc dotenv copies
- forgetting which setup is active
Profiles stop that from becoming normal.
Same project requirements, different local context — that is the real purpose of profiles.
What problem they solve¶
Profiles let one machine satisfy the same shared contract in multiple valid ways.
Typical examples:
localfor normal daily developmentdockerfor a container-oriented setupdev-altfor another backend or accountci-likefor local reproduction of pipeline assumptions
Explicit selection matters because many “wrong value” problems are really profile-selection problems:
$ envctl --profile local check
$ envctl --profile dev-alt run -- python app.pyWhat they are not¶
Profiles do not change:
- the contract
- required variables
- shared metadata
- repository-level environment shape
So profiles are not alternate contracts and they are not shared runtime truth.
How they fit in the system¶
Profiles sit between local storage and runtime truth:
- the contract stays shared
- the vault stores local values
- a profile selects one local set
- resolution computes what is true for this run
That is why profiles pair naturally with validation and runtime selection, but not with shared contract mutation.