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 | Current 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, 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
checkout
From the root, envshed checkout staging switches all workspaces to staging. Use --workspace to switch only one:
$ envshed --workspace apps/web checkout staging
[apps/web] Switched environment: development → staging
run
run requires a single workspace context. From the root, use --workspace:
$ envshed --workspace apps/api run -- npm start
branch
Shows all workspaces and highlights the current one:
$ envshed branch
org: my-company
Path Project Env File
* apps/web web-frontend development .env.local
apps/api backend-api development .env
packages/db backend-api development .env
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 CLI offers to set up workspace mappings for each package:
$ envshed init
Found 5 packages. Select which to configure:
❯ ◉ apps/web
◉ apps/api
◯ apps/landing
◯ packages/db
◯ packages/shared
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.