Skip to main content

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:

FieldDescriptionRequiredDefault
projectEnvshed project slugYes
defaultEnvCurrent environment slugNo
fileEnv file name (relative to workspace root)No.env
orgOverride the top-level org for this workspaceNoTop-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 locationBehavior
Inside a workspace dir (e.g., apps/web/)Commands operate on that workspace only
At the monorepo rootpull, push, checkout operate on all workspaces; run requires --workspace
With --workspace <path> flagCommands 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.