Env profiles
An env profile is a named .env file. Strado finds them when you add a repo,
and lets each worktree pick which one its dev server runs against.
What a profile is
Two fields, and no more:
| Field | What it is |
|---|---|
name | The label you pick it by. |
envFile | The file the start command is pointed at. |
They come from detection: every .env and .env.* file in the project
directory becomes a profile, skipping anything ending in .example, .sample
or .template. .env is named DEFAULT; the rest take their suffix,
uppercased — .env.staging becomes STAGING. The first one found becomes the
repo's default.
Wiring the start command
A profile does not carry a command. It substitutes into one.
When a repo has profiles, its start command must contain the {ENV_FILE}
placeholder. Whatever your project already uses to load an env file goes in the
start command, with {ENV_FILE} where the filename belongs, and Strado swaps
in the selected profile's file before running it — so a command written against
{ENV_FILE} runs against .env.staging when STAGING is selected.
Heads up
Detection fills in profiles and a start command independently, and the
detected command has no placeholder. So a repo with .env files will refuse
to start until you put {ENV_FILE} into its start command — the error says
exactly that, and nothing is spawned. Edit the start command when you add the
repo, in the Advanced section.
Which profile gets used
Resolved in this order, first match wins:
The profile this worktree is set to.
The repo's default profile.
The first profile in the repo's list.
Switching a worktree's profile while its dev server is running stops it and starts it again on the new one. Switching while stopped records the choice and nothing else.
Per-worktree overrides
Every worktree can override what its repo says. All of it lives in the worktree's settings.
| Override | Falls back to | Notes |
|---|---|---|
| Port | The repo's default port | Assigned at creation; editable afterwards. |
| Env profile | The repo's default profile | Only profiles the repo declares are accepted. |
| Start command | The repo's start command | Replaces it wholesale. |
| Preview URL | the detected URL, then http://localhost:<port> | The default URL a Browser tab opens for this worktree. |
| Env variables | nothing | Key/value pairs injected into the dev server at start. |
Set a preview URL and it wins outright. Leave it blank and a Browser tab opens
whatever URL the dev server announced in its own output, falling back to
http://localhost: and the worktree's port.
A worktree start command that contains {ENV_FILE} still participates in
profiles. One that does not is taken literally, with no error — the assumption
being that you chose a fixed command on purpose.
Note
PORT is set from the worktree's assigned port and wins over anything you
put in the env variables list. Pin a port by editing the worktree's port,
not by setting PORT yourself.
Where this is stored
Profiles and the repo default live in that workspace's repos.json; a
worktree's chosen profile, port, command and variables live beside it in
state.json. Both sit under config/workspaces/<id>/.