Concepts
This page explains the model behind the CLI. Open the concepts overview
Metadata and Local State¶
This page covers the supporting metadata that envctl keeps locally.
Its job is operational continuity and recovery, not becoming a second source of truth.
What metadata is¶
Local metadata is the helper state that lets envctl reconnect a checkout to the right local project state and recover more safely when paths or local context change.
Why it matters¶
envctl needs a small amount of local support data for things like:
- project identity
- recovery after a repository move or clone
- continuity across checkouts
- known local paths and related recovery hints
That support layer matters operationally, but it still stays secondary.
What problem it solves¶
Metadata solves continuity and recovery. It does not solve shared requirements or local secret storage.
That distinction prevents a common failure mode:
a helper file quietly becomes the real system model
What metadata is not¶
Metadata is not:
- the contract
- the vault
- the resolved environment
- a replacement for profiles
If it started doing those jobs, envctl would gain a hidden second model that would be harder to trust and harder to debug.
How it fits in the system¶
Keep the roles separate:
- the contract is shared repository truth
- the vault stores local values
- binding connects the checkout to the right project state
- metadata helps that binding and recovery story remain stable