Concepts
This page explains the model behind the CLI. Open the concepts overview
Projection¶
Projection is the step where a resolved environment leaves the internal model and is handed to another tool.
It is how runtime truth becomes usable outside envctl.
What it is¶
Projection answers one question:
How does the resolved environment reach the thing that needs it?
That target might be a subprocess, a generated dotenv file, or another explicit handoff surface.
Why it matters¶
Many environment failures are not contract failures and not local-storage failures. They are handoff failures.
Typical pattern:
checkpassesinspectlooks right- the application still sees something else
At that point, the problem usually lives in projection.
You can have correct resolution and still have incorrect projection.
What problem it solves¶
Projection keeps runtime handoff explicit instead of guessed.
Common projection paths are:
runfor subprocess injectionexportfor stdout-oriented outputsyncfor file-based handoff
One clear example is enough to show the idea:
$ envctl run -- python app.py
$ envctl export --format dotenvWhat it is not¶
Projection is not:
- the contract
- local storage
- the resolved environment itself
- whatever variables happen to be in your shell already
It is a deliberate handoff from resolved truth to a target surface.
How it fits in the system¶
Projection comes after resolution:
- the contract defines requirements
- local values and profiles define the current context
- resolution computes what is true
- projection hands that truth to tools
That is why validation alone does not guarantee correct runtime behavior. The target still has to receive the right handoff.