envshed workspace
Manage monorepo workspaces. Workspaces let you map multiple packages in a monorepo to different Envshed projects and environments, each with its own env file name.
Usage
envshed workspace add <path>
envshed workspace remove <path>
envshed workspace list
Subcommands
workspace add <path>
Interactively add a workspace to .envshed.json. Prompts for project, environment, and env file name.
$ envshed workspace add apps/web
Configure workspace: apps/web
? Project for apps/web: web-frontend
? Default environment for apps/web: development
? Env file name for apps/web: .env.local
Added workspace apps/web
workspace remove <path>
Remove a workspace entry from .envshed.json.
$ envshed workspace remove apps/web
? Remove workspace "apps/web" from config? Yes
Removed workspace apps/web
workspace list
List all configured workspaces with their project, environment, and file settings.
$ envshed workspace list
org: my-company
apps/web
project: web-frontend env: development file: .env.local
apps/api
project: backend-api env: development file: .env
Workspace config format
When workspaces are configured, .envshed.json looks like this:
{
"org": "my-company",
"workspaces": {
"apps/web": {
"project": "web-frontend",
"defaultEnv": "development",
"file": ".env.local"
},
"apps/api": {
"project": "backend-api",
"defaultEnv": "development"
},
"packages/db": {
"project": "backend-api",
"defaultEnv": "development"
}
}
}
Each workspace entry supports:
| Field | Description | Required | Default |
|---|---|---|---|
project | Envshed project slug | Yes | - |
defaultEnv | Shared default environment slug | No | - |
file | Env file name (relative to workspace root) | No | .env |
org | Override the top-level org for this workspace | No | Top-level org |
How workspaces affect other commands
When .envshed.json contains a workspaces field, the CLI automatically detects which workspace you are in based on your current directory:
| Your location | Behavior |
|---|---|
Inside a workspace dir (e.g., apps/web/) | Commands operate on that workspace only |
| At the monorepo root | pull, push, env checkout operate on all workspaces; run requires --workspace |
With --workspace <path> flag | Commands operate on the specified workspace regardless of CWD |
pull / push
From the monorepo root, envshed pull pulls secrets for all workspaces, writing each env file to the correct location:
$ envshed pull
my-company / web-frontend / development
✔ Wrote 12 secrets to apps/web/.env.local
my-company / backend-api / development
✔ Wrote 8 secrets to apps/api/.env
my-company / backend-api / development
✔ Wrote 8 secrets to packages/db/.env
Pulled secrets for 3 workspaces
env checkout
From the root, envshed env checkout staging switches all workspaces to staging. Use --workspace to switch only one:
$ envshed --workspace apps/web env checkout staging
[apps/web] Switched environment: development → staging
Selection updates personal context only, without editing files or shared defaults. The former local-change and export behavior is available only in explicit legacy compatibility mode.
run
run requires a single workspace context. From the root, use --workspace:
$ envshed --workspace apps/api run -- npm start
branch
Reports the effective environment, source, shared default and API destination. At the root it lists all workspace contexts; inside a workspace it reports that workspace. Use --output json for structured output.
Setting up workspaces
Interactive setup
Run envshed init at the monorepo root. If a pnpm-workspace.yaml or package.json with workspaces is detected, the setup screen lists the apps it found, each with the project it connects to:
App Project
❯ repository root choose a project
apps/api api
apps/web web-frontend (new)
packages/shared not connected · no .env files
Example with sample data.
Press enter on a row to pick an existing project, create a new one or choose Don't connect. The first line of the step switches to one project for the whole repository. See The setup screen.
Adding workspaces one at a time
envshed init --workspace apps/web
# or
envshed workspace add apps/web
Backward compatibility
If .envshed.json has no workspaces field, all commands behave exactly as before (single project mode). No migration is needed.
Personal environment selection
envshed --workspace apps/web env staging saves a personal selection for that workspace without changing .envshed.json or exporting values. Bulk pull/push and individual operations use -e > ENVSHED_ENV > personal selection > workspace default. Lifecycle scripts resolve context from their package directory. See configuration resolution.
Guided multi-application setup
In the plan flow (flags, --yes, no terminal), a single envshed init selects one or several applications, reuses or creates their remote projects after reviewing a consolidated plan, and preserves existing root projects/mappings. It also recognizes application folders without a formal workspace declaration. Use init --all -o my-team -e development --yes --no-guide only for an intentional batch plan. See init for discovery limits and independent-repository configuration placement.