Configuration Resolution
The CLI resolves settings from multiple sources, with higher-priority sources overriding lower ones.
Organization, project, and environment
Organization and project resolve from CLI flags, then the selected workspace mapping, then the applicable project configuration (organization may inherit from the root).
Environment resolves in this order:
| Priority | Source |
|---|---|
| 1 | -e / --env for this command |
| 2 | ENVSHED_ENV inherited from the shell |
| 3 | Personal checkout/workspace selection in ~/.envshed/contexts.json |
| 4 | Shared defaultEnv in .envshed.json for the applicable project/workspace |
Individual and bulk operations share this resolution. Each workspace has its own default; it does not silently inherit the root project's environment. Missing required fields fail with an actionable error.
Use envshed branch (alias context) to inspect the effective environment and its source. envshed env staging saves only the personal selection. envshed env checkout --reset removes it. Neither changes shared defaults or exports secrets. CI ignores personal selections and keeps flag/shell/shared defaults; prefer an explicit target in automation. OIDC policies continue to determine their authorized target.
API URL
| Priority | Source |
|---|---|
| 1 (highest) | --api-url flag (on login and init) |
| 2 | apiUrl in .envshed.json - loopback hosts only |
| 3 | apiUrl in ~/.envshed/config.json |
| 4 | ENVSHED_API_URL environment variable |
| 5 (lowest) | Default: https://app.envshed.com |
A remote apiUrl in the committed .envshed.json is ignored (with a
warning): since that file is usually shared via a repository, honoring an
arbitrary host there would let it redirect your bearer token to an
attacker-controlled server. Use the global config or ENVSHED_API_URL for
remote/self-hosted instances.
Authentication token
| Priority | Source |
|---|---|
| 1 (highest) | ENVSHED_TOKEN environment variable |
| 2 | An OIDC session (envshed run --oidc only), or an agent session for this environment (envshed run only) |
| 3 | token in ~/.envshed/config.json, which moves to the keychain when one is available |
| 4 | The OS keychain |
ENVSHED_OIDC_POLICY or --oidc together with ENVSHED_TOKEN is an error, so an OIDC job cannot quietly use another credential.
There is no flag to pass a token per-command. Use envshed login, envshed token set --token-stdin, or set the ENVSHED_TOKEN environment variable. See where the token is stored.
Working directory
When running the CLI via pnpm --filter, the working directory changes to the package directory. Lifecycle scripts resolve from the package directory (cwd), so filtered scripts select their package workspace rather than the root from INIT_CWD. Outside lifecycle scripts, INIT_CWD is used when available, then cwd. Configuration discovery walks ancestors from that directory. If no .envshed.json is found, the personal connection of the enclosing git checkout is used (see Only for me).
Output masking
For envshed run, whether stdout and stderr are masked resolves in this order:
| Priority | Source |
|---|---|
| 1 (highest) | --redact or --no-redact |
| 2 | --oidc or ENVSHED_OIDC_POLICY: enable |
| 3 | ENVSHED_AGENT_MODE: 0, false, no, off disable, other values enable |
| 4 | CLAUDE_CODE_CHILD_SESSION=1, set by Claude Code in commands it launches |
| 5 (default) | Off |
See output masking.
Terminal overrides
For POSIX shells, export ENVSHED_ENV=staging applies to subsequent commands in that terminal; remove it with unset ENVSHED_ENV. In PowerShell use $env:ENVSHED_ENV = "staging" and remove it with Remove-Item Env:ENVSHED_ENV. For one execution across shells, prefer envshed run -e staging -- <command>. Neither form saves a personal selection.