Environment Format

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 persisted request snapshots, request search, code generation, and exports; server response fields remain intact.

Linux and headless environments

On Linux, Noodle uses the Secret Service API through a provider such as GNOME Keyring or KWallet. A desktop session normally starts and unlocks the provider for you. On a headless server, you must provide a user D-Bus session and an unlocked keyring collection.

Install a provider and the command-line Secret Service tools first:

# Ubuntu/Debian
sudo apt install gnome-keyring libsecret-tools dbus-user-session

# Fedora
sudo dnf install gnome-keyring libsecret

# Arch
sudo pacman -S gnome-keyring libsecret

Run Noodle inside the same user D-Bus session as the keyring. If a foreground gnome-keyring-daemon --start process is already running, stop it with Ctrl+C first:

dbus-run-session -- bash
read -rsp "Keyring password: " KEYRING_PASSWORD
printf "\n"
eval "$(printf '%s\n' "$KEYRING_PASSWORD" | gnome-keyring-daemon --unlock --components=secrets)"
unset KEYRING_PASSWORD
noodle --collection ./my-api

The --unlock step creates or unlocks the login collection without requiring the graphical SystemPrompter. Keep Noodle in that shell; a separate SSH shell will not share its D-Bus session. For unattended jobs, provide the same-named secret through the process environment or use an external secret manager instead of depending on an interactively unlocked keyring.

Troubleshooting

• Object does not exist at path .../collection/login means the login keyring collection is missing or locked. Run the headless setup above.
• couldn't initialize prompt or SystemPrompter GTK warnings mean the keyring tried to open a graphical prompt. Use gnome-keyring-daemon --unlock with the password supplied on stdin.
• cookies plaintext means Noodle could not access the OS vault and used a mode-0600 fallback for the cookie jar. Restart Noodle after fixing the keyring.

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.

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.