Multi-Environment Setup

Rumour makes it easy to switch your test executions across different target environments (such as development, staging, or production) by swapping environment configuration files.

Workspace Directory Structure

A common practice is to define a default workspace.env.toml for local development, and create dedicated configuration files for other targets:

project/
├── workspace.env.toml        # Default config (e.g., local/dev)
├── staging.env.toml          # Staging config
├── prod.env.toml             # Production config
├── auth/
│   └── login.toml
└── users/
    └── get_user.toml

Choosing an Environment

1. Default Loading Behavior

If a workspace.env.toml file exists in your project root, Rumour automatically detects and loads its variables for every execution. You do not need to pass any extra parameters:

# Automatically loads workspace.env.toml if present
rumour run auth/login.toml

2. Custom Environment Loading

To execute requests against a non-default environment, pass the path of the environment file using the -e or --env-file flag:

# Run against the staging environment
rumour run auth/login.toml -e staging.env.toml

# Run against the production environment
rumour run auth/login.toml -e prod.env.toml

note

The -e file provides a baseline layer of variables that are available to all requests in a run. However, any auto-discovered .env.toml file in the request's directory tree takes priority over -e values for that specific request. To guarantee a value wins regardless of any local env file, use a CLI override (-V) instead. See [Variable Precedence](/ environments/variable-precedence) for the full priority stack.

3. CLI Variable Overrides

For quick, one-off changes without modifying any files, override individual variables directly from the command line:

# Override a single variable for this run
rumour run auth/login.toml -V "base_url=http://localhost:8080"

# Combine with environment file selection
rumour run auth/login.toml -e staging.env.toml -V "debug=true"

CLI -V overrides have the highest priority among non-vault sources.

Best Practices & Version Control

To prevent sensitive environment configurations from being leaked or causing sync issues, follow these conventions:

1. Gitignore Sensitive Environment Files

Avoid committing environment files that contain real credentials or environment-specific URLs. Add patterns to your .gitignore as appropriate:

# .gitignore
# Exclude environment-specific configs with real credentials
staging.env.toml
prod.env.toml

# Or exclude all env files and rely on .example templates
# *.env.toml

tip

workspace.env.toml can be safely committed if it only contains non-sensitive defaults (e.g., base_url = "http://localhost:3000") or vault references (e.g., token = "{{vault.api_token}}"). Only exclude it if it contains raw credentials.

2. Provide Template Examples

Create and commit template configuration files (with .example suffixes) containing empty or mock values. This documents the required variables for team members without exposing live credentials:

# workspace.env.toml.example
base_url = "https://api-dev.example.com"
api_version = "v2"
github_token = "YOUR_VAULT_KEY_HERE"

To use the template, developers copy the example file:

cp workspace.env.toml.example workspace.env.toml

3. Use Vault for Secrets

Instead of placing raw API keys or passwords in .env.toml files, store them in the encrypted Rumour Vault and reference them:

# workspace.env.toml — safe to share in templates
base_url = "https://api.github.com"
github_token = "{{vault.github_token}}"

See [Encrypted Vault Secrets](/ variables/vault-variables) for setup instructions.