Environments

Environment files (stored in environments/) allow you to define configuration that changes between stages like Dev, Staging, and Production. Plyson supports both JSON and standard Dotenv formats.

JSON Format (*.env.json)

JSON environment files provide a structured way to define environment variables and base URLs.

Fields

• $schema (Optional): Points to the environment schema for Intellisense.
• baseUrl (Required): The root URL for all API requests in this environment.
• specUrl (Optional): The URL to your OpenAPI/Swagger specification, used by the CLI for schema synchronization.
• variables (Optional): Environment-specific overrides for your global variables.

Dotenv Format (*.env)

Standard Dotenv files are also supported and are ideal for quick overrides or local development.

Reserved Keys

• baseUrl or BASE_URL: Overrides the environment's base URL.
• specUrl or SPEC_URL: Overrides the OpenAPI spec URL.
• ANY_OTHER_KEY: Becomes an environment-specific variable.

Resolution Priority

If multiple sources define the same variable or baseUrl, Plyson uses the following priority order (highest to lowest):

1. System Environment Variables (CI/CD overrides)
2. Dotenv File (*.env)
3. JSON File (*.env.json)
4. Global Variables (variables.json)

CI/CD & System Environment Variables

For security and predictability, Plyson follows a "Declared Variables Only" rule when picking up variables from your system environment (like GitHub Actions secrets or terminal exports):

Rule: System environment variables will only override variables that already exist (even if empty) in your variables.json or environment files.

Why?

This prevents Plyson from polluting your test store with hundreds of unrelated system variables (like PATH, USER, or HOME) and ensures only intended variables are exposed to your tests.

Example for CI/CD

To use a secret like API_KEY in your pipeline without a .env file, you must first declare it as a placeholder in your variables.json:

// variables.json
{
  "API_KEY": "" 
}

Then, in your CI environment (e.g., GitHub Actions):

env:
  API_KEY: ${{ secrets.MY_SECRET_KEY }}

Plyson will see the declared API_KEY, check the system environment, and use the value from your secret.

Example: Merging Files

dev.env.json

{
  "baseUrl": "https://api.dev.json",
  "variables": {
    "DEBUG": true,
    "RETRIES": 3
  }
}

dev.env

baseUrl=https://api.dev.env
DEBUG=false
API_KEY=secret_123

Resulting Environment:

• baseUrl: https://api.dev.env (from .env)
• DEBUG: false (from .env)
• RETRIES: 3 (from .json)
• API_KEY: secret_123 (from .env)

CLI Command

To add a variable to all your environment files at once:

npx plyson generate env-var <key> <value> --env <name>

• key / value: The variable to add.
• --env <name>: The specific environment where the value should be set (others will receive an empty string placeholder).

Example (dev.env.json)

{
  "$schema": "../Project-schema/environment.schema.json",
  "baseUrl": "http://localhost:3000",
  "specUrl": "http://localhost:3000/openapi.json",
  "variables": {
    "adminEmail": "dev-admin@example.com"
  }
}