Environments

Environments let you define variables that change between contexts - like different API URLs for development and production, or different API keys per environment.

---

Overview

An environment is a named set of variables. Common use cases:

• Development vs Production - Different base URLs, API keys
• Per-user configuration - Personal API tokens
• Testing scenarios - Mock data, test credentials

Variables are substituted in URLs, headers, body content, and authentication fields.

---

Creating Environments

Press ctrl+shift+e to open the environment manager.

1. Select Create New Environment
2. Enter a name (e.g., “development”, “production”, “staging”)
3. Add variables with key-value pairs

Environments are stored in environments/ within your workspace as JSON files.

---

Variable Substitution

Use double curly braces to reference variables:

{{VARIABLE_NAME}}

Variables can be used in:

• URL - https://{{API_HOST}}/users
• Headers - Authorization: Bearer {{API_TOKEN}}
• Query params - api_key={{API_KEY}}
• Body - {"user": "{{USERNAME}}"}
• Auth fields - Token, username, password, API key values

Missing Variables

When a variable is referenced but not defined in the active environment, t-req shows a warning in the header bar indicating the number of undefined variables.

---

Variable Sources

Variables can get their values from different sources:

Inline Values

The default - values stored directly in the environment file.

environments/development.json

{
  "name": "development",
  "variables": [
    { "key": "API_HOST", "value": "localhost:3000" },
    { "key": "DEBUG", "value": "true" }
  ]
}

Secrets

Values resolved from a companion .secrets.json file. Use this for sensitive data that shouldn’t be committed to version control. For direct substitution from system environment variables, see Direct Interpolation.

environments/development.json

{
  "name": "development",
  "variables": [
    { "key": "API_HOST", "value": "localhost:3000", "type": "text", "enabled": true },
    { "key": "API_TOKEN", "value": "", "valueSource": "secrets", "type": "secret", "enabled": true }
  ]
}

environments/development.secrets.json

{
  "API_TOKEN": "sk-secret-token-here"
}

The .secrets.json files are gitignored by default.

System Environment Variables

Values resolved from system environment variables at runtime.

environments/ci.json

{
  "name": "ci",
  "variables": [
    { "key": "API_TOKEN", "value": "", "valueSource": "env:CI_API_TOKEN", "type": "secret", "enabled": true }
  ]
}

This reads the value of CI_API_TOKEN from the system environment.

Direct Interpolation

Use {env:VARIABLE_NAME} to substitute system environment variables directly in request fields:

• URL: https://api.example.com?token={env:API_TOKEN}
• Header: Authorization: Bearer {env:AUTH_TOKEN}
• Body: {"key": "{env:SECRET_KEY}"}

Request body example

{
  "apiKey": "{env:MY_API_KEY}",
  "secret": "{env:MY_SECRET}"
}

Values substituted via {env:} are automatically redacted from request history.

Tip

Use this for CI/CD pipelines or containerized environments where secrets are provided via system environment variables.

---

Switching Environments

From UI

Press ctrl+shift+e to open the environment manager and select an environment to activate.

Or use the command palette (ctrl+p) and search for “Switch Environment”.

Active Environment

The active environment name is shown in the footer bar. All requests use variables from the active environment.

---

Secrets Management

The Secrets File

Each environment can have an associated secrets file:

environments/
├── development.json
├── development.secrets.json    (gitignored)
├── production.json
└── production.secrets.json     (gitignored)

Gitignore Setup

t-req automatically adds *.secrets.json to .gitignore when you create your first environment with secrets. You can also add it manually:

.gitignore

# t-req secrets
*.secrets.json

Best Practices

1. Never commit secrets - Always use the secrets file or env vars for sensitive data
2. Use descriptive names - STRIPE_API_KEY not KEY1
3. Document required variables - List expected variables in your README
4. Provide example files - Create example.secrets.json with placeholder values

Example secrets template:

environments/example.secrets.json

{
  "API_TOKEN": "your-api-token-here",
  "DATABASE_PASSWORD": "your-password-here"
}

---

Environment File Format

environments/production.json

{
  "id": "env-abc123",
  "name": "production",
  "created": 1704067200000,
  "updated": 1704153600000,
  "inherits": "base",
  "variables": [
    {
      "key": "API_HOST",
      "value": "api.example.com",
      "type": "text",
      "enabled": true,
      "description": "Production API endpoint"
    },
    {
      "key": "API_TOKEN",
      "value": "",
      "valueSource": "secrets",
      "type": "secret",
      "enabled": true
    },
    {
      "key": "LOG_LEVEL",
      "value": "",
      "valueSource": "env:LOG_LEVEL",
      "type": "text",
      "enabled": true
    }
  ]
}

Environment Fields

Field	Type	Description
id	string	Unique identifier for the environment
name	string	Environment name
created	number	Unix timestamp (ms) when created
updated	number	Unix timestamp (ms) when last modified
inherits	string?	Parent environment ID for layered inheritance
variables	array	List of variable definitions

Variable Fields

Field	Type	Default	Description
key	string	—	Variable name (used in {{key}} syntax)
value	string	""	Inline value
valueSource	string?	—	Value source: "secrets" or "env:VAR_NAME"
type	"text" | "secret"	"text"	Variable type (secrets are masked in UI)
enabled	boolean	true	Whether variable is active
description	string?	—	Optional description for documentation

---

Managing Variables via CLI

You can create, update, and delete environment variables directly from the command line using the treq workspace env var commands.

Adding Variables

# Text variable with inline value
treq ws env <env> var add <key> --value "value"

# Secret (will prompt for value securely)
treq ws env <env> var add <key> --type secret

# Secret with explicit value
treq ws env <env> var add <key> --type secret --value "secret-value"

# Secret referencing a system environment variable
treq ws env <env> var add <key> --type secret --source env:SYSTEM_VAR

# With description
treq ws env <env> var add <key> --value "value" --description "Description here"

Examples:

# Add API URL to production
treq ws env production var add API_URL --value "https://api.example.com"

# Add API key as a secret (will prompt)
treq ws env production var add API_KEY --type secret

# Reference CI environment variable
treq ws env ci var add DB_PASSWORD --type secret --source env:CI_DATABASE_PASSWORD

Updating Variables

# Update with new value
treq ws env <env> var set <key> "new value"

# Update interactively (prompted)
treq ws env <env> var set <key>

For secrets, omitting the value will prompt with masked input.

Deleting Variables

# Delete with confirmation
treq ws env <env> var delete <key>

# Delete without confirmation
treq ws env <env> var delete <key> --force

Toggling Variables

Disable a variable without deleting it:

treq ws env <env> var toggle <key>

Disabled variables are preserved in the environment file but not included during variable resolution.

For complete CLI reference, see CLI Commands.

---

Dynamic Variables from Hooks

Hooks can dynamically set environment variables that persist across sessions. This is useful for storing auth tokens, session IDs, or any other values extracted from responses.

Setting Variables

login.hooks.js

export const post = async (ctx) => {
  if (ctx.response.ok) {
    const { access_token } = ctx.response.json()
    await ctx.env.set('ACCESS_TOKEN', access_token)
    ctx.log.info('Token saved to environment')
  }
}

The value is immediately:

• Available via ctx.env.get('ACCESS_TOKEN') in the same hook
• Saved to the active environment file on disk
• Available as {{ACCESS_TOKEN}} in subsequent requests

Auth Flow Example

1. Create a login request to your auth endpoint
2. Add a post-hook that extracts and saves the token:

   export const post = async (ctx) => {
     const { token } = ctx.response.json()
     await ctx.env.set('AUTH_TOKEN', token)
   }

3. Use {{AUTH_TOKEN}} in subsequent requests’ Authorization header
4. The token persists across TUI sessions

Running with Environment

# Run login to save token to dev environment
treq run login -e dev

# Run protected request using saved token
treq run get-profile -e dev

# Run entire collection
treq run my-api -e dev

---

Related

• HTTP Mode - Using variables in requests
• Collections - Organizing requests
• Scripts - Accessing variables in hooks