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

SubcommandDescription
env listList all environments in a project
env createCreate a new environment
env updateUpdate an environment's name or description
env deleteDelete an environment
env duplicateDuplicate an environment with all its secrets
env checkoutSwitch the active environment (alias: envshed env <slug>)

envshed env list​

List all environments in a project.

terminal
envshed env list [options]
OptionDescriptionRequired
-o, --org <slug>Organization slugYes (or via config)
-p, --project <slug>Project slugYes (or via config)
--output <format>Output format: jsonNo

Example:

terminal
$ envshed env list
Name Slug Description
─────────────────────────────────────────────
Development development
Staging staging
Production production

envshed env create​

Create a new environment in a project.

terminal
envshed env create --name <name> [options]
OptionDescriptionRequired
-n, --name <name>Environment nameYes
-d, --description <text>Environment descriptionNo
-o, --org <slug>Organization slugYes (or via config)
-p, --project <slug>Project slugYes (or via config)
--output <format>Output format: jsonNo

Example:

terminal
$ envshed env create --name staging
✓ Environment 'staging' created (slug: staging)

JSON output:

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

terminal
envshed env update <slug> [options]
OptionDescriptionRequired
<slug>Environment slug to updateYes
-n, --name <name>New environment nameNo (at least one of --name or --description)
-d, --description <text>New descriptionNo (at least one of --name or --description)
-o, --org <slug>Organization slugYes (or via config)
-p, --project <slug>Project slugYes (or via config)
--output <format>Output format: jsonNo

Example:

terminal
$ envshed env update staging --name "Staging v2"
✓ Environment 'Staging v2' updated (slug: staging-v-2)

Note: If the environment being updated is your defaultEnv in .envshed.json and its slug changes, the CLI automatically updates .envshed.json to use the new slug.


envshed env delete​

Delete an environment permanently. This action is irreversible.

terminal
envshed env delete <slug> [options]
OptionDescriptionRequired
<slug>Environment slug to deleteYes
-o, --org <slug>Organization slugYes (or via config)
-p, --project <slug>Project slugYes (or via config)
-y, --yesSkip confirmation promptNo
--output <format>Output format: jsonNo

Example (with confirmation):

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

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

terminal
envshed env duplicate <source-slug> --name <new-name> [options]
OptionDescriptionRequired
<source-slug>Source environment slugYes
-n, --name <name>Name for the new environmentYes
-o, --org <slug>Organization slugYes (or via config)
-p, --project <slug>Project slugYes (or via config)
--output <format>Output format: jsonNo

Example:

terminal
$ envshed env duplicate staging --name staging-copy
✓ Environment 'staging-copy' duplicated (slug: staging-copy)

JSON output:

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

terminal
envshed env staging
envshed env checkout staging
envshed env switch staging
envshed env checkout --reset
Argument / optionDescription
[slug]Existing environment to select
--resetRemove the personal selection; cannot be combined with a slug
--legacy-syncExplicit 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:

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