Reinvent your coding workflow. Spin up many worktrees with correctly wired apps and supporting services, automatic port allocation to avoid conflicts, isolated databases, Redis, Supabase, and n8n, then manage everything from one CLI with logs, health checks, and parallel testing across trees.
README · Getting Started · Contributing · License
envctl is a global CLI for orchestrating full local development environments across one repository and many worktrees. It starts apps, assigns safe ports, wires dependencies, keeps each environment isolated, and gives you one place to operate the whole system.
This is the point where normal local development usually starts breaking down: two backends want the same port, one frontend points at the wrong API, a shared Redis or database leaks across branches, logs are split across terminals, and parallel implementations become difficult to compare safely.
envctl turns that into a deterministic workflow. It tracks runtime state per worktree, keeps service and dependency wiring isolated, and gives you a single command surface for startup, tests, logs, health, inspection, PR/review flows, and teardown. The result is faster iteration, fewer environment mistakes, and a much better base for both human and AI-assisted development.
Currently supported stack: the documented runtime is the Python engine.
envctlcurrently supports Python backends, JavaScript frontends, multi-worktree orchestration, and built-in local service wiring for databases plus Redis, Supabase, and n8n.
# 1) Install envctl once so it is available in every shell
pipx install "git+https://github.com/kfiramar/envctl.git"
pipx ensurepath
# 2) Go to a target repo
cd /path/to/your-project
# 3a) Start one repo-local environment
# If .envctl is missing, envctl opens the guided setup wizard.
envctl --main
# 3b) Or work from plans and let envctl manage worktrees for you
# Use this when you want parallel implementations side by side.
mkdir -p todo/plans/backend
cat > todo/plans/backend/checkout.md <<'PLAN'
# Checkout Implementation Plan
PLAN
envctl --planThat first interactive run is the normal setup path. The wizard writes the repo-local .envctl for you, whether you start in main mode or jump straight into plan-driven worktrees.
envctl is built to:
- create and manage many worktrees with isolated local services
- run and compare multiple implementations side by side
- keep startup, logs, tests, inspection, and health checks behind one CLI
- support high-throughput human and AI-assisted development workflows
Start here:
User docs:
Reference:
Operations and troubleshooting:
Developer docs:
Project docs:
pipx installs envctl itself. Depending on the repo and workflow, you may also need:
gitfor repository detection, worktrees, commits, reviews, and PR preparationdockerfor built-in local services such as databases, Redis, Supabase, and n8nghfor GitHub PR creation flowspoetryfor backend repositories that manage Python dependencies with Poetry- one JavaScript package manager for frontend apps:
bun,pnpm,yarn, ornpm, depending on the repo
envctl bootstraps target-repo dependencies from the repo itself, so tools such as pytest are usually installed as part of the backend project rather than separately for envctl.
envctl writes and maintains a repo-local .envctl.
- On first interactive use, the setup wizard creates it for you.
- Later, run
envctl configto reopen the wizard and edit it safely. docs/reference/.envctl.exampleis the reference file for managed keys and defaults, not the primary onboarding flow.