Guides

This page applies the model to a real workflow. Open the guides overview

Profiles¶

Guide

Profiles let one machine keep more than one local value set for the same contract. They are the clean way to switch local context without mutating shared project requirements.

If you want the definition of profiles rather than the workflow, start with the Profiles concept.

Why profiles exist¶

One repository often needs more than one local setup.

Typical examples:

local development with one account
local development with another account
a second integration target
temporary side-by-side testing
different local ports or machine-owned endpoints

Without profiles, people often drift toward brittle habits:

copying dotenv files around
renaming files manually
overwriting values in place
forgetting what changed

Profiles exist to stop that mess from becoming normal.

What a profile changes¶

A profile changes local stored values.

It does not change:

the contract
required variables
shared defaults
descriptions
validation rules

That distinction is the whole point.

Use profiles when the project stays the same but your local execution context changes.

Create a profile¶

When you want a second local context, create it explicitly:

create profile

$ envctl profile create dev

If you like, think of this as creating a new local namespace of values.

Fill missing values for that profile¶

Once the profile exists, populate only what is missing there:

fill profile

$ envctl --profile dev fill

This keeps the values scoped to that profile instead of overwriting your default local setup.

Validate it¶

Before you trust it, validate it:

check profile

$ envctl --profile dev check

This tells you whether that selected local value set satisfies the same shared contract.

Run with it¶

Once validated, use it directly:

run profile

$ envctl --profile dev run -- python app.py

Same contract, different local context.

That is exactly what profiles are for.

See what profiles exist¶

Use this when you want a quick overview of local profile names:

list profiles

$ envctl profile list

Copy an existing profile¶

Sometimes the second profile is almost the same as the first one.

In that case, copy it and then change only what is different:

copy profile

$ envctl profile copy local staging-like

That is often cleaner than rebuilding a second profile from scratch.

Remove a profile you no longer need¶

If a local context is obsolete, remove it explicitly:

remove profile

$ envctl profile remove dev

This keeps local profile sprawl under control.

See where a profile lives¶

If you want to inspect profile-local storage path information directly:

profile path

$ envctl profile path
$ envctl profile path dev

That is useful when debugging local storage layout.

A practical pattern¶

A very normal setup on one machine might be:

local → normal daily development
dev-alt → second local backend or second account
ci-like → a local profile used to mimic CI constraints

The important part is that all three still point to the same contract.

When not to use profiles¶

Do not use profiles as if they were alternate contracts.

If the application requirements changed for everyone, that is not a profile problem. That is a contract change.

A quick rule:

shared project requirements changed → update the contract
my local context changed → use profiles