Skip to content
envctl

Quick start

If envctl is not installed yet, see Install. Then, from the root of a repository that has a compose file:

Terminal window
envctl init --project mg --file app/docker-compose.yml

This writes envctl.yaml. The project prefix becomes the first part of every compose project name, so keep it short. Add .envctl/ to .gitignore; that is where rendered files go.

Start the environment

Section titled “Start the environment”
Terminal window
envctl up

envctl derives a feature name from your branch, renders an isolated copy of the stack, starts it, and waits for health checks. The output ends with the services, their endpoints, and the env file for host tooling:

env       fix-metergraph-capitalization
branch    fix/metergraph-capitalization
project   mg-fix-metergraph-capitalization
backend   local
rendered  .envctl/fix-metergraph-capitalization/compose.yaml
services
  postgres             running    healthy
env       source .envctl/fix-metergraph-capitalization/env

Run envctl up again any time. It converges the environment instead of failing because it already exists.

Reach a service

Section titled “Reach a service”

On OrbStack, every service has a DNS name and no host port is published:

Terminal window
psql -h postgres.mg-fix-metergraph-capitalization.orb.local -U metergraph

Elsewhere, envctl allocates a stable loopback port per service and records it in the env file:

Terminal window
set -a; . .envctl/fix-metergraph-capitalization/env; set +a
psql -h 127.0.0.1 -p "$ENVCTL_PORT_POSTGRES_5432" -U metergraph

envctl status prints both forms, and envctl status --json prints them for scripts.

Start a second one

Section titled “Start a second one”

Check out another branch in a second worktree and run envctl up there. You now have two complete stacks with separate networks, volumes, and names:

Terminal window
envctl list
mg-fix-metergraph-capitalization                 running(1)
mg-main                                          running(1)

Stop, keep, or remove

Section titled “Stop, keep, or remove”
GoalCommand
Pause, keep dataenvctl stop then envctl start
Remove containers, keep dataenvctl down
Remove everything including volumes and portsenvctl down -v

Where next

Section titled “Where next”
  • Concepts explains features, environments, and port modes.
  • How to work with envctl covers Makefiles, native test runners, and several branches at once.
  • Agents wires Claude Code worktrees to environments.

Where next

Section titled “Where next”