Skip to content

Approvals and trust ​

pw-env keeps two different trust boundaries separate.

The two approval types ​

ApprovalControlsDefault scope
Project override approvalWhether .pw-env.toml may change the effective configThe exact file content hash
Secret-fetch approvalWhether a project .env may trigger backend lookups or export plaintext values with source_allThe exact .env hash for the project

Project-local overrides ​

Place a .pw-env.toml file in a project when that repository needs different backend settings than the global config.

pw-env searches upward from the current directory until it reaches the repository root. If it finds .pw-env.toml on that walk, it only loads the file after the current content hash is approved.

Useful commands:

console
pw-env approvals show .
pw-env approvals approve .
pw-env approvals revoke .
pw-env approvals list

If the file changes after approval, pw-env prompts again in interactive sessions. When the current override is not approved, automatic environment loading is suspended until you approve or remove the file. Commands that request environment values fail closed while the override is unapproved.

Secret-fetch approvals ​

Before pw-env resolves empty values or explicit backend references from .env, it checks whether the project is approved to fetch secrets. The same approval also protects plaintext-only files when source_all is enabled, because those values can affect the shell or child-process environment.

By default, approval is tied to the current .env hash. That keeps a reviewed .env file approved while still forcing a fresh approval when the file changes.

Useful commands:

console
pw-env approvals show-fetch .
pw-env approvals approve-fetch .
pw-env approvals approve-fetch . --project-wide
pw-env approvals revoke-fetch .
pw-env approvals list-fetch

Use --project-wide only when you want future .env changes in the same project to skip the reapproval step.

Suggested team workflow ​

  1. Review .pw-env.toml like any other project config change.
  2. Approve the local override with pw-env approvals approve ..
  3. Approve .env use with pw-env approvals approve-fetch ..
  4. Revisit the approval when .env or .pw-env.toml changes.

Where approval state lives ​

Approval data is stored in the platform state directory used by pw-env, not inside the project repository. That keeps approval state local to each machine.