envshed env
Manage environments in a project. The env command groups all environment lifecycle operations into a single namespace.
Note:
envshed env <slug>(checkout shorthand) continues to work for backward compatibility.
Subcommands
| Subcommand | Description |
|---|---|
env list | List all environments in a project |
env create | Create a new environment |
env update | Update an environment's name or description |
env delete | Delete an environment |
env duplicate | Duplicate an environment with all its secrets |
env checkout | Switch the active environment (alias: envshed env <slug>) |
envshed env list
List all environments in a project.
envshed env list [options]
| Option | Description | Required |
|---|---|---|
-o, --org <slug> | Organization slug | Yes (or via config) |
-p, --project <slug> | Project slug | Yes (or via config) |
--output <format> | Output format: json | No |
Example:
$ envshed env list
Name Slug Description
─────────────────────────────────────────────
Development development
Staging staging
Production production
envshed env create
Create a new environment in a project.
envshed env create --name <name> [options]
| Option | Description | Required |
|---|---|---|
-n, --name <name> | Environment name | Yes |
-d, --description <text> | Environment description | No |
-o, --org <slug> | Organization slug | Yes (or via config) |
-p, --project <slug> | Project slug | Yes (or via config) |
--output <format> | Output format: json | No |
Example:
$ envshed env create --name staging
✓ Environment 'staging' created (slug: staging)
JSON output:
$ envshed env create --name staging --output json
{
"environment": {
"name": "staging",
"slug": "staging"
}
}
envshed env update
Update an environment's name or description. If the name changes, the slug is automatically derived from the new name and .envshed.json is updated if the environment was your defaultEnv.
envshed env update <slug> [options]
| Option | Description | Required |
|---|---|---|
<slug> | Environment slug to update | Yes |
-n, --name <name> | New environment name | No (at least one of --name or --description) |
-d, --description <text> | New description | No (at least one of --name or --description) |
-o, --org <slug> | Organization slug | Yes (or via config) |
-p, --project <slug> | Project slug | Yes (or via config) |
--output <format> | Output format: json | No |
Example:
$ envshed env update staging --name "Staging v2"
✓ Environment 'Staging v2' updated (slug: staging-v-2)
Note: If the environment being updated is your
defaultEnvin.envshed.jsonand its slug changes, the CLI automatically updates.envshed.jsonto use the new slug.
envshed env delete
Delete an environment permanently. This action is irreversible.
envshed env delete <slug> [options]
| Option | Description | Required |
|---|---|---|
<slug> | Environment slug to delete | Yes |
-o, --org <slug> | Organization slug | Yes (or via config) |
-p, --project <slug> | Project slug | Yes (or via config) |
-y, --yes | Skip confirmation prompt | No |
--output <format> | Output format: json | No |
Example (with confirmation):
$ envshed env delete staging
? Are you sure you want to delete environment 'staging'? This cannot be undone. (y/N) y
✓ Environment 'staging' deleted
Skip confirmation:
$ envshed env delete staging --yes
✓ Environment 'staging' deleted
Warning: Deleting an environment permanently removes all its secrets and audit logs. This cannot be undone.
envshed env duplicate
Duplicate an environment, copying all its secrets into a new environment with the given name.
envshed env duplicate <source-slug> --name <new-name> [options]
| Option | Description | Required |
|---|---|---|
<source-slug> | Source environment slug | Yes |
-n, --name <name> | Name for the new environment | Yes |
-o, --org <slug> | Organization slug | Yes (or via config) |
-p, --project <slug> | Project slug | Yes (or via config) |
--output <format> | Output format: json | No |
Example:
$ envshed env duplicate staging --name staging-copy
✓ Environment 'staging-copy' duplicated (slug: staging-copy)
JSON output:
$ envshed env duplicate staging --name staging-copy --output json
{
"environment": {
"name": "staging-copy",
"slug": "staging-copy"
}
}
Note: The server verifies you have read access to the source environment before creating the copy.
envshed env checkout
Select an environment for this checkout without changing the shared project default or exporting secrets.
envshed env staging
envshed env checkout staging
envshed env switch staging
envshed env checkout --reset
| Argument / option | Description |
|---|---|
[slug] | Existing environment to select |
--reset | Remove the personal selection; cannot be combined with a slug |
--legacy-sync | Explicit compatibility mode: change shared defaults and synchronize env files |
Selections live in ~/.envshed/contexts.json, separately for each checkout, workspace, trusted API destination and org/project binding. They contain metadata only. A selection affects future commands in every terminal using that checkout/workspace, not processes already running. Separate worktrees are independent.
Resolution is -e > ENVSHED_ENV > personal selection > shared defaultEnv. Reset removes only the personal source: a shell override still wins. Run envshed branch (alias context) to inspect the effective environment and its source.
The CLI validates all selected targets before saving any changes. A missing environment is an error; create it explicitly with env create. Potential production selections require confirmation. No values are downloaded or uploaded when selecting context, and an existing .env is preserved.
Monorepos
Inside a mapped workspace, selection applies to that workspace. At the root, it applies to the configured workspaces (and the root project when configured). Use envshed --workspace apps/web env staging to select one explicitly. Each workspace uses its own defaultEnv; a missing workspace default does not inherit the root environment silently.
Migration from 0.22
Starting in 0.23, envshed env staging only selects context. If a script previously relied on automatic file export, replace it with explicit operations:
envshed env staging
envshed pull -e staging
Export prompts protect existing local values. Use --force only when intentional. For a transition period, envshed env staging --legacy-sync retains the old shared-default mutation, local-change prompt and file synchronization behavior. This compatibility mode can upload local changes or overwrite files, so review its prompts. It is not the recommended daily flow.
CI ignores personal selections; existing shared defaults still work. Prefer an explicit -e, ENVSHED_ENV or an OIDC policy target for automation. Existing files and defaults are not migrated or removed automatically.