Namespaced Environment Variables

In Rumour, environment-specific configurations (such as base URLs, ports, database stages, or version numbers) are conventionally organized under the env. variable namespace.

This prefix acts as a virtual namespace inside your .env.toml files to keep configuration files self-documenting and isolated from request-specific dynamic outputs.

important

Rumour does not automatically read host operating system/process environment variables at runtime. The env. prefix is a naming convention for variables defined in your workspace environment files. The only OS-level environment variable Rumour reads directly is RUMOUR_VAULT_PASS (used for vault decryption).

Defining Namespaced Variables

Because TOML keys containing dots are parsed as nested tables by default, you must quote the key names when defining env. prefixed variables at the root level of your .env.toml files.

Syntax (workspace.env.toml)

base_url = "http://localhost:3000"

# Quoted keys — creates flat key "env.ENV_STAGE" in the variable map
"env.ENV_STAGE" = "staging"
"env.API_VERSION" = "v2"
"env.TEST_VAR" = "hello_env_toml"

warning

Do not use unquoted dotted keys. Writing env.STAGE = "prod" (without quotes) creates a nested TOML table [env] with key STAGE, which Rumour cannot parse as a flat variable. Always quote dotted keys: "env.STAGE" = "prod".

Using the [variables] Table

Environment files also support a [variables] table. When defining env. prefixed keys inside this table, quoting is still required:

[variables]
"env.DB_HOST" = "db.staging.internal"
"env.DB_PORT" = "5432"

Values in the [variables] table override duplicate root-level keys with the same name.

Supported Value Types

The environment file loader accepts the following TOML value types, converting non-string types to their string representation:

TOML Type	Example	Stored As
String	"staging"	staging
Integer	8080	8080
Float	3.14	3.14
Boolean	true	true

Tables, arrays, and other complex TOML types at the root level are silently ignored.

Referencing in Requests

You can reference env. prefixed variables in any part of a request (URL, headers, query params, or body) using the standard {{}} placeholder syntax:

name = "env_var_test"

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

[headers]
X-Test = "{{env.TEST_VAR}}"

[assert]
status = 200

Resolved Output Example

Given the workspace.env.toml shown above, running the request produces:

{
  "headers": {
    "X-Test": "hello_env_toml"
  }
}

Binding Host System Variables via CLI

If you need to pass actual host operating system environment variables (such as a local shell $API_TOKEN or shell-specific $PORT) into your requests, you must explicitly bind them using CLI overrides (-V) at runtime.

CLI Command Example

# Explicitly bind local OS shell variables to Rumour's variable namespace
rumour run request.toml -V "env.TOKEN=$API_TOKEN" -V "env.PORT=$PORT"

The shell expands $API_TOKEN and $PORT before Rumour receives them, so the resolved key-value pairs are inserted directly into the runtime variable map.

Overriding File-Defined Values

CLI overrides (-V) have the highest priority in the variable resolution stack. If the same key is defined in both a .env.toml file and a -V flag, the CLI value wins:

# Overrides the "env.TEST_VAR" from workspace.env.toml
rumour run request.toml -V "env.TEST_VAR=cli_override_value"

Resolved Output Example

{
  "headers": {
    "X-Test": "cli_override_value"
  }
}

note

Using the env. prefix is a best-practice convention in Rumour. It distinguishes environment configurations from runtime-extracted variables (like tokens extracted from a login response) and vault secrets ({{vault.secret_key}}).