Environment Files

Environment files in Rumour are simple TOML configurations used to define variables across multiple request executions. They help separate target URLs, credentials, and settings from request templates.

File Structure & Format

Rumour environment files must use the .env.toml suffix. Inside the file, variables can be defined in one of two ways:

1. At the root level of the file (flat key-values), or
2. Under a [variables] table.

Both methods load into the same flat variable scope. If the same key appears at both the root level and inside [variables], the [variables] entry wins.

warning

Sub-tables like [env], [headers], or [params] are not supported in environment files. Any nested table declarations other than [variables] will be silently ignored by the loader.

Example Structure (workspace.env.toml)

# Root-level configuration
base_url = "https://api.example.com"
api_version = "v2"
timeout = 30

# Variables table section (also loaded into the workspace scope)
[variables]
debug = true
admin_email = "admin@example.com"

Workspace Root Boundary

The presence of a workspace.env.toml file defines the workspace root. Rumour uses this file as the boundary when scanning for environment files up the directory tree. The workspace.env.toml file itself is also loaded as part of the cascading scan — it serves as both the boundary marker and the lowest-priority environment file. If no workspace.env.toml is found, Rumour falls back to the .git directory as the root boundary.

Variable Types

The environment loader supports standard TOML primitive types. All values are stored internally as strings:

TOML Type	Example	Stored As
String	base_url = "https://api.example.com"	https://api.example.com
Integer	timeout = 30	30
Float	backoff_factor = 1.5	1.5
Boolean	debug = true	true

note

At the root level, tables, arrays, and other complex TOML types are silently ignored — only primitive key-value pairs are loaded. Inside the [variables] table, complex types (arrays, inline tables) are accepted and stored as their TOML string representation (e.g., [1, 2, 3]). This is an advanced edge case; stick to primitives for predictable behavior.

Namespaced Keys

Keys containing dots (such as env.API_KEY) must be quoted in TOML to prevent them from being parsed as nested tables:

# Correct — creates a flat key "env.API_KEY"
"env.API_KEY" = "my_key_value"

# Wrong — creates nested table { env: { API_KEY: "..." } } which is ignored
env.API_KEY = "my_key_value"

See the [Environment Variables](/ variables/environment-variables) documentation for details on using the env. naming convention.

Secret Mapping with Vault

To keep your configuration files clean and secure, map variables to your encrypted vault using the {{vault.secret_key}} syntax. This prevents committing raw passwords or API keys to version control.

Mapping Vault Secrets

In your workspace.env.toml:

base_url = "https://api.github.com"
github_token = "{{vault.github_token}}"

Referencing in Request Templates

In your request .toml files, reference the environment variable name:

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

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

During execution, Rumour automatically performs nested resolution: resolving {{github_token}} to the raw string {{vault.github_token}}, and then resolving the vault placeholder by decrypting the secret in-memory. This requires the RUMOUR_VAULT_PASS environment variable to be set.

See [Encrypted Vault Secrets](/ variables/vault-variables) for full details on vault management.

Directory Cascading

When you run a request, Rumour automatically scans all .env.toml files from the workspace root down to the request's directory. Files are loaded in order of increasing priority:

1. Workspace root (lowest priority) — loaded first.
2. Intermediate directories — loaded next, overriding root values.
3. Request's own directory (highest priority) — loaded last, overriding everything above.

Within the same directory, multiple .env.toml files are loaded in alphabetical order, so later-sorted files override earlier ones.

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

Running rumour run tests/auth/login.toml resolves base_url to http://local.api (nearest file wins).

See [Variable Precedence & Resolution](/ environments/variable-precedence) for the full priority stack.