Variable Resolution

Rumour provides a powerful, hierarchical variable resolution engine that allows requests to share data dynamically across files, directories, and pipeline stages.

Variable Sources

Variables enter the Rumour runtime from four distinct sources, merged in a strict priority order (see Priority Precedence below):

1. Environment Files (*.env.toml)

Defined in any file ending with .env.toml (e.g., workspace.env.toml, dev.env.toml). Variables must be declared at the root level of the file or under a [variables] table.

# workspace.env.toml
base_url = "https://api.example.com"
api_version = "v2"
timeout = 30

[variables]
admin_email = "admin@example.com"

warning

Sub-tables such as [env], [headers], or [params] are not loaded from environment files. Only root-level keys and keys under the [variables] section are recognized. All other TOML tables are silently ignored.

Environment File Cascading

When you run a request, Rumour scans for all .env.toml files starting from the workspace root folder down to the directory of the target request file:

• Farthest files (workspace root) are loaded first and have the lowest priority.
• Nearest files (the request's own directory) are loaded last and override variables from higher up.
• Multiple .env.toml files within the same directory are sorted and loaded alphabetically — files that come later alphabetically override earlier ones (e.g., z_dev.env.toml overrides a_dev.env.toml).

The Workspace Boundary

The file named workspace.env.toml has a special system-level role: Rumour uses its presence to determine the workspace root boundary. The engine walks up the directory tree until it finds workspace.env.toml. If none is found, it falls back to the nearest .git/ directory to identify the workspace root.

2. Extracted Variables

Variables can be extracted dynamically from the HTTP response of a request using two methods: Explicit Extraction and Intelligent Auto-Extraction.

Method A: Explicit Extraction ([extract] block)

Declare explicit JSON path or response header extractions inside the request file:

name = "login"

[request]
method = "POST"
url = "{{base_url}}/auth/login"

[body]
type = "json"
raw = '{"username": "test", "password": "secret"}'

[extract]
token        = "json.access_token"
user_id      = "json.user.id"
email        = "json.user.email"
session_id   = "header.x-session-id"

Use extracted variables in subsequent requests:

[request]
method = "GET"
url = "{{base_url}}/users/{{user_id}}"

[headers]
Authorization = "Bearer {{token}}"

Explicit extractions are inserted into the runtime as both a flat key and a namespaced key (e.g., token and login.token). They take precedence over auto-extracted values with the same name.

Method B: Intelligent Auto-Extraction

Even without an [extract] block, Rumour's built-in Intelligent Extraction Engine automatically parses the JSON responses of successful requests. It recursively traverses the JSON tree (up to a depth of 10 levels), matching keys against a registry of known security, identity, and session patterns:

Canonical Name	Registry Aliases
accessToken	token, access_token, accessToken, auth_token, authToken, jwt, bearer, api_key, apiKey, authorization, auth
adminAccessToken	admin_token, adminAccessToken, admin_access_token, adminToken
refreshToken	refresh_token, refreshToken, refresh
id	user_id, userId, uid, uuid, account_id, accountId, id, guid
sessionId	session_id, sessionId, sid, session, csrf, xsrf, token_id, X-CSRF-TOKEN, X-XSRF-TOKEN
version	v, ver, version
status	state, status

Fuzzy Substring Matching: In addition to the registry aliases above, the engine automatically extracts any JSON key whose normalized name contains "token", "secret", "key", "id", or "sid" as a substring — provided the key is longer than the matched substring (e.g., product_id is extracted under its original name product_id, but the short key "id" alone is matched via the registry directly).

All auto-extracted variables are populated as both a flat key (e.g., id) and a namespaced key (e.g., login.id, using the request file stem as the prefix). Explicit extractions always take precedence over auto-extracted values for the same key name.

3. Collection Configuration

Variables can also be defined in collection configuration files which cascade down through the directory hierarchy alongside env files. Rumour recognizes the following collection config filenames (in priority order per directory, farthest first):

• *.config.toml (e.g., auth.config.toml) — primary format
• _collection.toml — legacy support
• collection.toml — legacy support
• collection.env.toml — legacy support

Collection configs can define shared [headers], [params], and [variables] applied to all requests in and below their directory.

4. CLI Runtime Overrides

Override any variable at the command line using the -V (--var) flag:

rumour run request.toml -V base_url=https://staging.api.com -V api_version=v3

To load a completely different environment configuration file:

rumour run request.toml -e prod.env.toml

5. Vault Secrets

Reference encrypted vault secrets using the vault. prefix:

[headers]
Authorization = "Bearer {{vault.api_key}}"

See the Encrypted Vault Secrets guide for setup and CLI commands.

Priority Precedence

When the same variable key is defined in multiple sources, Rumour resolves it using the following priority order (highest to lowest):

Priority	Source	How to set
1 (Highest)	CLI Runtime Overrides	-V key=value / --var key=value
2	CLI Custom Environment File	-e custom.env.toml
3	Hierarchical Environment Files	*.env.toml (nearest dir wins)
4	Collection Configuration	*.config.toml, collection.toml, etc.
5	Request-Level Variables	[variables] block in request .toml

important

Because CLI overrides and environment files are merged into the execution runtime before request-local [variables] are evaluated, a variable defined in a .env.toml file will override a variable with the same name defined in a request's own [variables] block. Use CLI overrides (-V) to force a specific value regardless of any file-based definition.

Placeholder Syntax

Rumour supports three placeholder styles, all resolved during the same pass:

Style	Example	Use case
Double-brace	{{base_url}}	Standard variable references
Single-brace	{user_id}	Compact style for simple identifiers
Colon-prefix	/users/:id	URL path parameter style

All three styles resolve from the same variable pool. Double-brace syntax is preferred for clarity and is supported everywhere (URL, headers, body, params, and assertions).

Nested Resolution

Rumour resolves placeholders up to 3 levels deep. This means you can reference a variable whose value itself contains a placeholder. A common use case is vault-backed environment variables:

# workspace.env.toml
github_token = "{{vault.github_token}}"

# In a request:
[headers]
Authorization = "Bearer {{github_token}}"

During execution, the engine resolves {{github_token}} → {{vault.github_token}} → the decrypted vault secret in a single pass.

Extraction Syntax Reference

JSON Path

Rumour uses dot-notation for JSON path extraction. Array elements are accessed by index using dot-notation numbers.

[extract]
# Simple field
token = "json.access_token"

# Nested field
user_name = "json.data.user.name"

# Array index (zero-based)
first_id  = "json.items.0.id"
second_id = "json.items.1.id"

Header Extraction

Prefix the path with header. followed by the header name. Header names are lowercased before lookup, so always use lowercase names in extraction paths.

[extract]
session_id   = "header.set-cookie"
request_id   = "header.x-request-id"
server_name  = "header.server"

Namespace Isolation & Flat Keys

When a request extracts variables (either via [extract] or auto-extraction), they are inserted into the runtime in two forms:

1. Flat Key (e.g., token): Accessible by any downstream request without a prefix. If multiple requests extract the same flat key, the later request's value overwrites the earlier one.
2. Namespaced Key (e.g., login.token): Prefixed with the request file's stem name (filename without .toml). This value is isolated and preserved throughout the entire workflow execution, even if another request later overwrites the flat key.

[headers]
# Resolves to the specific token extracted by login.toml — stable regardless of later extractions
Authorization = "Bearer {{login.token}}"

# Resolves to the most recently extracted flat 'token', or falls back to env/collection/request variables
Authorization = "Bearer {{token}}"

Complete Workflow Example

1. Login (auth/login.toml)

name = "login"

[request]
method = "POST"
url = "{{base_url}}/auth/login"

[body]
type = "json"
raw = '{"email": "test@example.com", "password": "secret"}'

[extract]
access_token  = "json.access_token"
refresh_token = "json.refresh_token"

2. Get Profile (users/profile.toml)

name = "get_profile"

[request]
method = "GET"
url = "{{base_url}}/users/me"

[headers]
Authorization = "Bearer {{access_token}}"

[extract]
user_id  = "json.id"
username = "json.username"

3. Update Profile (users/update.toml)

name = "update_profile"

[request]
method = "PUT"
url = "{{base_url}}/users/{{user_id}}"

[headers]
Authorization = "Bearer {{access_token}}"

[body]
type = "json"
raw = '{"username": "{{username}}_updated"}'

Data-Driven Testing

Use --data with a CSV or JSON file to run the same workflow multiple times — once per row:

user_id,email
1,alice@example.com
2,bob@example.com

[request]
method = "GET"
url = "{{base_url}}/users/{{user_id}}"

rumour run users/ --data users.csv

This runs the workflow once per row, binding each row's columns as variables.

Debugging Variables

Inspect Runtime Variables (--vars)

Print all runtime variables after execution. Secret values (vault-backed) are automatically masked:

rumour run ./requests/ --vars

Output:

RUNTIME VARIABLES:
  01_login.accessToken = abc123token
  01_login.id          = 42
  01_login.user_name   = Alice
  vault.api_key        = [MASKED]

note

The --vars output lists all runtime variable keys alphabetically. Extracted variables appear under both their short namespaced form (e.g. 01_login.accessToken) and an absolute-path-prefixed form (e.g. /workspace/auth/01_login.toml.01_login.accessToken). Both resolve to the same value and can be referenced using their short form in request files.

Verbose Mode (-v)

Print step-by-step details of URL and header resolution:

rumour run request.toml -v

Best Practices

1. Use namespaced keys for stability — Reference {{login.token}} instead of {{token}} when you need a guaranteed value from a specific request.
2. Use vault for secrets — Never define passwords or API keys as plain strings in .env.toml files. Map them to vault keys instead.
3. Use workspace.env.toml as the root anchor — Its presence defines the workspace boundary; keep it at the project root.
4. Provide .example templates — Commit a workspace.env.toml.example file with placeholder values so teammates know which variables to define.
5. Pin critical values with CLI overrides — Use -V key=value in CI/CD pipelines to set environment-specific variables that must not be overridden by any file.