Project Config (.envshed.json)

The project config file stores defaults for the current project so you don't need to pass flags on every command.

Location

The CLI searches for .envshed.json starting from the current directory and walking up to the filesystem root. This means it works from any subdirectory of your project.

When no .envshed.json is found, the CLI uses the personal connection of the enclosing git checkout, if one exists: the same file stored on your machine at ~/.envshed/connections/<id>/.envshed.json by envshed init --personal. A .envshed.json in the repository always wins over a personal connection.

Format

json

{
  "org": "my-org",
  "project": "my-project",
  "defaultEnv": "development",
  "apiUrl": "http://localhost:3005"
}

Field	Description	Required
org	Organization slug	Yes
project	Project slug	Yes
defaultEnv	Default environment slug	No
apiUrl	API URL override - loopback only (e.g. http://localhost:3005), for local development	No

warning

Because .envshed.json is usually committed to a shared repository, apiUrl here is honored only when it points at a loopback host (localhost, 127.0.0.1, ::1). A remote apiUrl in project config is ignored (with a warning) so a committed file cannot redirect your access token to another host. To target a self-hosted/remote instance, set apiUrl in ~/.envshed/config.json or the ENVSHED_API_URL environment variable instead.

Creating the file

Use envshed init to generate the file:

terminal

envshed init -o my-org -p my-project -e development

Or create it manually. The web dashboard also provides a copyable config snippet on the project page: open More (top right) and pick Use from the CLI.

Switching environments

Use envshed env to save a personal checkout selection without changing the shared defaultEnv:

terminal

envshed env staging

The personal selection is stored outside the repository in ~/.envshed/contexts.json. Run envshed branch to inspect its effective value and source. Use envshed env checkout --reset to remove it. Edit the project configuration intentionally when the team default should change. No secret values or tokens belong in either context file.

Monorepo setup

Using Envshed in a monorepo? The workspaces block in .envshed.json is how pnpm/Turborepo/Nx teams scope secrets per package. Read the full monorepo secrets guide for walkthroughs, the failure modes of common patterns, and a public demo repo.

Monorepo workspaces

For monorepos with multiple packages that need different env files, use the workspaces field:

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:

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

Root project alongside workspaces

The top-level project and defaultEnv fields can coexist with workspaces. This is useful when the monorepo root itself is a project (e.g., for shared infrastructure secrets):

json

{
  "org": "my-company",
  "project": "monorepo-root",
  "defaultEnv": "development",
  "workspaces": {
    "apps/web": {
      "project": "web-frontend",
      "defaultEnv": "development"
    },
    "apps/api": {
      "project": "backend-api",
      "defaultEnv": "development"
    }
  }
}

When both project and workspaces are present, the CLI resolves context as follows:

• At the monorepo root: operates on the root project and all workspaces together (bulk mode)
• Inside a workspace directory: uses only that workspace's project
• With --all flag: same as root - operates on everything in bulk
• With --workspace <path>: uses only the specified workspace's project

If only workspaces is present (no top-level project), the root operates on all workspaces in bulk.

Set up workspaces with:

terminal

# Interactive multi-workspace setup (detects pnpm/npm workspaces)
envshed init

# Add a single workspace
envshed init --workspace apps/web

# Or use the workspace command
envshed workspace add apps/web

See envshed workspace for full details.

Git

Add .envshed.json to your repository so all team members share the same project config. The file does not contain secrets.