quickstart.md

Quickstart

Getting started

This page is the shortest safe path from zero to a validated first run. It is intentionally practical: install envctl, initialize local state, fill what is missing, validate, and run.

When to use this page

Use this page when:

• you want the fastest successful setup
• you do not need the deeper theory first
• you are comfortable following a short command sequence

If you want more context before touching a repository, read Mental model first.

Shortest safe path

quickstart

$ envctl config init
$ envctl init
$ envctl fill
$ envctl check
$ envctl run -- python app.py

What each step is doing

1. envctl config init

Creates your user-level config file so the CLI has machine-local defaults such as vault location and default profile.

2. envctl init

Prepares the repository for contract-based workflows and establishes local state where needed.

3. envctl fill

Prompts only for required values that are still missing from the active profile.

4. envctl check

Validates the resolved environment against the shared contract.

5. envctl run -- …

Projects the resolved environment into one subprocess without writing a dotenv file by default.

Prefer `run` unless another tool explicitly needs a file on disk. Use `sync` only for file-based consumers.

Optional next step: use a named profile

If one machine needs more than one local setup, make that explicit:

named profile

$ envctl profile create dev
$ envctl --profile dev fill
$ envctl --profile dev check
$ envctl --profile dev run -- python app.py

Read next

### First project

Follow the same flow with more repository context and a few realistic checks.

Open first project

### Mental model

Learn why the quickstart steps work the way they do.

Open mental model

### Daily workflow

Move from first setup into the normal day-to-day command rhythm.

Open daily workflow