Getting started
Start here when you want the shortest path to a working setup. Open the getting started overview
First project¶
Use this page when you have cloned a real repository and want a little more context than the quickstart. The goal is still practical: get from fresh checkout to a validated, runnable local setup without mixing shared requirements and local values.
Starting point¶
This page assumes:
- the repository already uses
envctl - you want to prepare your machine, not redesign the project contract
- you want a first successful run and a reliable next step if something is missing
Step 1: create your local config¶
$ envctl config initThis creates your machine-level config. It controls tool behavior such as vault location and default profile. It does not define the project contract and it does not store the project’s shared requirements.
Step 2: initialize the repository¶
$ envctl initinit prepares the checkout for normal envctl use. It may establish local structure, binding, and managed hook wrappers where supported.
init prepares local state, not secrets
init can normalize local structure and recover project state. It does not invent or guess the real values your machine needs.
Step 3: inspect what is already ready¶
$ envctl statusThis is the fastest way to answer the practical question:
what is already ready, and what is still missing?
If you also want to confirm the managed hook layer, check it directly:
$ envctl hooks statusStep 4: fill missing required values¶
$ envctl fillThis prompts only for values that are both:
- required by the contract
- missing from the active profile
Step 5: validate¶
$ envctl checkIf validation fails, stay at this layer first. Fix the model before debugging a downstream runtime.
Step 6: run the project¶
$ envctl run -- python app.py
$ envctl run -- npm start
$ envctl run -- make devFor most local workflows, run is the right default because it keeps projection explicit and ephemeral.
If you need a second local context¶
Create a named profile instead of mutating one local setup in place:
$ envctl profile create dev
$ envctl --profile dev fill
$ envctl --profile dev check
$ envctl --profile dev run -- python app.py