Pular para o conteúdo principal
informação
Esta página ainda não foi traduzida. Você está lendo a versão em English.

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​

terminal
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.

terminal
$ 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.

terminal
$ 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.

terminal
$ 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:

json
{
"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-
defaultEnvShared default 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, env 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:

terminal
$ 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:

terminal
$ 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:

terminal
$ 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:

output
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​

terminal
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.