Why penv adopted @env-spec instead of inventing a schema format

Description and use

penv adopted the @env-spec format for .env schemas, eliminating learning curve and ensuring interoperability with varlock. Custom decorators extend functionality for cloud integration.

Problem

Developers need a schema for .env files to enforce types, required keys, and sensitive values, but creating a custom format adds learning curve and interoperability issues.

Outcome

By adopting @env-spec, penv achieved zero learning curve, easy schema generation, and interoperability with existing tools, while adding its own decorators for cloud integration.

Workflow

• 1. Use @env-spec decorators in a .env.schema file to declare types, sensitivity, and other metadata.
• 2. Run penv init to generate the schema from an existing .env file and gitignore the .env.
• 3. Add custom decorators (@since, @rotate, @dynamicFrom) and headers (@schema, @penv) for penv-specific features.
• 4. Commit the .env.schema file; penv reads it for validation and agent execution.
• 5. For non-sensitive values, include them directly in the schema; secrets are managed in the cloud.
• 6. If needed, drop the same .env.schema into varlock for local loading.
• 7. Avoid .env.* cascade; penv uses a single .env file and cloud environments.
• 8. Use penv’s per-harness guards and typed codegen for secure agent sessions.

Evidence

penv’s .env.schema is an @env-spec file.

Source

penv init reads the .env you already have, writes the schema next to it, and gitignores .env.

Source