Environment files

Environment files use dotenv format and live under <collection>/.environments/. One .env file per environment.

File Format

_color=success
base_url=https://api.example.com
# @secret api_key
api_key=
# disabled_key=this_is_disabled

Rules

• KEY=value: Active public variable, available for $KEY substitution
• # KEY=value: Disabled variable. Prefix with # to exclude from substitution
• # @secret KEY + blank KEY=: Enabled secure declaration. The value comes from process.env.KEY when defined, otherwise from the OS credential vault.
• # @secret KEY + # KEY=: Disabled secure declaration. Secure placeholders must stay blank and immediately follow their marker.
• _color=<name>: Sets sidebar badge color for this environment
• Public, disabled, and secret keys must match ^\w+$; _color is reserved.
• Values preserve everything after the first = exactly, including trailing spaces.

Use the environment editor or noodle secret set KEY --env <name> to store a secret. Noodle uses macOS Keychain, Linux Secret Service, or Windows Credential Manager and never writes the value into the .env file. Missing vault values remain declared but unresolved. Declared secret values are masked in the editor and redacted from request search, code generation, exports, structured run results, and newly saved request and response history. Sensitive response headers are masked too. Marking or updating a secret does not rewrite existing timeline entries; unknown server data may still be sensitive.

Linux and headless environments

For Secret Service setup, an unlocked keyring, and unattended jobs, see Linux and headless environments.

Troubleshooting

See keyring error messages and cookie storage recovery.

Badge Colors

Color	Badge
primary	Cyan
secondary	Blue
accent	Purple
error	Red
warning	Yellow
success	Green
info	Light blue

Convention

Environment	Recommended _color
Production	success (green)
Staging	warning (yellow)
Development	info (blue)

Variable Substitution

All $VARNAME references in request files are resolved against the active environment. Use $$ for one literal dollar: $$NAME sends $NAME, while $$$NAME sends a literal $ followed by the resolved value of NAME. Values resolve once and are not scanned again. Variables are applied to:

• url
• enabled headers values
• enabled params names and values
• path_params names and values
• body
• enabled form_data names and values
• file_path
• all string-valued auth fields, including OAuth credentials, endpoints, scopes, private keys, token placement names, and additional parameters
• string values nested inside assertion expectations

Unresolved variables cause noodle to throw an error at send time.

Script persistence and storage recovery

Inline pre/post scripts can call noodle.run.set/unset with { persist: "environment" | "secret" }. Manual sends and request run save to an existing selected environment; collection runs and the Runner keep changes transient. Environment operations cannot replace declared secrets. Secret set can promote an ordinary entry; secret unset removes both the vault value and declaration. CLI secret delete retains the declaration. Secret writes never fall back to plaintext. See Scripting.

Environment writes share a cross-process lock. For interrupted writers and timeouts, follow environment lock recovery.

Best Practices

• Always keep the same set of variable names across all environments. Different values, same keys.
• Comment out (#) variables that don’t apply to an environment; don’t delete the line.
• Use secure declarations for tokens, passwords, and API keys. Keep ordinary placeholders only for deliberately public test values.
• Put _color on the first line for visual clarity.