Variable Precedence & Resolution

When executing request suites, Rumour compiles dynamic values from multiple sources. To ensure predictable outcomes, Rumour evaluates variables using a strict hierarchy and cascading folder lookup logic.

1. Directory Cascading Rules

When you run a request, Rumour scans all files ending in .env.toml starting from the workspace root directory (where workspace.env.toml is located) down to the specific folder containing the target request file:

1. Farthest (Ancestors) First: Files at the workspace root or parent directories are resolved first. They establish baseline values and have the lowest priority.
2. Nearest (Local) Last: Files in the request's immediate directory are resolved last and overwrite keys defined higher up the directory tree.
3. Alphabetical Sorting (Tie-Breaker): If multiple .env.toml files reside in the same directory, they are loaded in alphabetical order. Files sorted later (e.g., z_dev.env.toml) overwrite those loaded earlier (e.g., a_dev.env.toml).

Directory Resolution Example

Given this directory layout:

project/
├── workspace.env.toml           # Defines base_url = "http://dev.api"
├── tests/
│   ├── staging.env.toml         # Defines base_url = "http://staging.api"
│   └── auth/
│       ├── local.env.toml       # Defines base_url = "http://local.api"
│       └── login.toml           # Request target

When executing login.toml, base_url resolves in this sequence:

1. workspace.env.toml sets it to http://dev.api.
2. tests/staging.env.toml overrides it to http://staging.api.
3. tests/auth/local.env.toml overrides it to http://local.api.

2. Priority Precedence Stack

During request execution, variables gathered from different scopes are merged. If a key is defined in multiple places, Rumour resolves conflicts using the following priority order (from highest to lowest):

Priority	Source	Description	Example
1 (Highest)	Vault Secrets	Encrypted secrets resolved via {{vault.*}} prefix	{{vault.stripe_key}}
2	Request-Level Variables	[variables] section defined inside the request .toml	[variables] in login.toml
3	Collection Config	[variables] inherited from .config.toml or collection.toml files	auth.config.toml
4	CLI Overrides (-V)	Explicit per-run key bindings passed via the command line	-V base_url="http://override.api"
5	Directory Environment Files	Cascaded .env.toml files — nearest directory wins over farthest	local.env.toml in target folder
6 (Lowest)	CLI Custom Env File (-e)	The file passed using the -e flag — provides baseline defaults only	-e staging.env.toml

important

Collection config and request [variables] take higher priority than -V CLI overrides. This means a -V flag cannot override a value that is hard-coded in the request's [variables] section or in a .config.toml collection file. Vault secrets are the only source that always wins unconditionally.

3. Precedence Scenario Checklist

If you want to determine which value of base_url wins, use this checklist:

1. Is base_url mapped to a vault secret ({{vault.base_url}})?
   • Yes: The vault-decrypted value wins. Nothing can override it.
   • No: Proceed.
2. Is base_url defined under [variables] inside the request .toml?
   • Yes: The request-local value wins.
   • No: Proceed.
3. Is base_url defined in a collection config (.config.toml / collection.toml)?
   • Yes: The collection-level value wins.
   • No: Proceed.
4. Did you pass -V base_url=...?
   • Yes: That value wins.
   • No: Proceed.
5. Is there a .env.toml file in the request's folder or parent folders?
   • Yes: The value in the nearest file (or alphabetically last file in that folder) wins.
   • No: Proceed.
6. Did you specify -e custom.env.toml?
   • Yes: The value inside custom.env.toml is used as a baseline fallback.
   • No: The placeholder is unresolved and will throw an audit warning or error.