Linking projects
A link tells the CLI which project and environment this directory belongs to, so pull, push, run and files need no flags in daily use. Links live in a plain .envpilot file you can commit.
Link a directory#
❯terminal
envpilot init
envpilot init -o <organization-id> -p <project-id> -e production
envpilot init --add # link an ADDITIONAL project to this directory
envpilot init --force # overwrite the existing linkInteractive by default: pick organization → project → default environment.
Multiple projects in one directory#
A monorepo often needs several: --add appends a link instead of replacing one. One link is active at a time; commands act on the active link unless you pass --project.
❯terminal
envpilot list linked # what this directory is linked to, and which is active
envpilot switch --active api # make the 'api' link activeSwitch the active target#
❯terminal
envpilot switch production # bare argument: a project slug or an environment name
envpilot switch --env production
envpilot switch --project api
envpilot switch --organization <id>
envpilot switch --active apiswitch edits local state only — it never rewrites your whole project config, and it never touches the server.
Unlink#
❯terminal
envpilot unlink
envpilot unlink api --forceRemoves the link and updates the active-project state. Existing .env files are left on disk untouched — unlinking is not a cleanup command.
Limits#
- A link is local. Nothing about it is stored server-side, and it grants no access by itself.
- The active link is per directory, not per shell — two terminals in the same folder share it.
- Environments are fixed at
development,staging,production;--envaccepts nothing else. unlinkdoes not delete secrets from disk. Delete the.envyourself, or let the VS Code extension clean up on revocation.