Skip to main content
Environment variables in Yasumu allow you to store and reuse values across different environments without hardcoding them in your requests. Each environment is stored as a .ysl file and can contain both regular variables and encrypted secrets.

​
Understanding environments

An environment contains:
  • Variables: Non-sensitive values like API URLs, user IDs, timeouts
  • Secrets: Sensitive values like API keys, tokens, passwords (stored securely)
Each workspace can have multiple environments (Development, Staging, Production, etc.) with one environment active at a time.

​
Environment file structure

Environments are stored in yasumu/environment/*.ysl: 
@environment

metadata {
  id: "c10t47a2kufpq46wt9oomc4d"
  name: "Production"
}

variables [
  {
    key: "API_URL"
    value: "https://api.production.com"
    enabled: true
  },
  {
    key: "API_VERSION"
    value: "v2"
    enabled: true
  },
  {
    key: "TIMEOUT"
    value: "30000"
    enabled: true
  },
]

secrets [
  {
    key: "API_TOKEN"
    value: "sk_prod_xxxxxxxxxxxxx"
    enabled: true
  },
  {
    key: "DATABASE_PASSWORD"
    value: ""
    enabled: true
  },
]

​
Creating environments

1

Open environment manager

Navigate to the Environment section in your workspace.
2

Create new environment

Click “New Environment” and provide a name (e.g., “Development”, “Staging”, “Production”).
3

Add variables

Add key-value pairs for non-sensitive configuration values.
4

Add secrets

Add sensitive values like API keys. These are stored securely and not committed to version control.
5

Activate environment

Set the environment as active to use its variables in requests.

​
Programmatic environment management

​
Creating an environment

const env = await workspace.environments.create({
  name: 'Development',
  variables: [
    { key: 'API_URL', value: 'http://localhost:3000', enabled: true },
    { key: 'API_VERSION', value: 'v1', enabled: true },
    { key: 'DEBUG', value: 'true', enabled: true }
  ],
  secrets: [
    { key: 'API_TOKEN', value: 'dev_token_here', enabled: true },
    { key: 'DB_PASSWORD', value: 'dev_password', enabled: true }
  ]
});

console.log(`Created environment: ${env.name}`);

​
Listing environments

// Get all environments
const environments = await workspace.environments.list();

for (const env of environments) {
  console.log(`Environment: ${env.name} (${env.id})`);
}

​
Getting a specific environment

// Get by ID
const env = await workspace.environments.get('environment-id');

if (env) {
  console.log(`Found: ${env.name}`);
}

​
Setting active environment

// Set active environment by ID
await workspace.environments.setActiveEnvironment('environment-id');

// Get currently active environment
const active = await workspace.environments.getActiveEnvironment();

if (active) {
  console.log(`Active: ${active.name}`);
}

​
Updating an environment

const env = await workspace.environments.get('environment-id');

// Update environment properties
await env.update({
  name: 'Development (Updated)',
  variables: [
    { key: 'API_URL', value: 'http://localhost:4000', enabled: true },
    { key: 'NEW_VAR', value: 'new_value', enabled: true }
  ]
});

​
Deleting an environment

await workspace.environments.delete('environment-id');

​
Working with variables

The EnvironmentVariable class provides methods to manage variables and secrets:

​
Setting variables

const env = await workspace.environments.getActiveEnvironment();

// Set a variable
await env.variables.set('API_URL', 'https://api.example.com');
await env.variables.set('TIMEOUT', '5000', true); // enabled

// Set a secret
await env.secrets.set('API_KEY', 'sk_live_xxxxxxxxxxxx');

​
Getting variables

// Get an enabled variable
const apiUrl = env.variables.get('API_URL');
if (apiUrl) {
  console.log(`URL: ${apiUrl.value}`);
}

// Get variable regardless of enabled state
const raw = env.variables.getRaw('API_URL');
console.log(`Enabled: ${raw?.enabled}`);

// Get all variable keys
const keys = env.variables.getKeys();
console.log(`Variables: ${keys.join(', ')}`);

​
Deleting variables

// Delete a specific variable
await env.variables.delete('OLD_VAR');

// Clear all variables
await env.variables.clear();

​
Variable interpolation

Yasumu automatically interpolates variables in your requests using the {{VARIABLE_NAME}} syntax.

​
Using variables in requests

await workspace.rest.create({
  name: 'Get User',
  method: 'GET',
  url: '{{API_URL}}/{{API_VERSION}}/users/{{USER_ID}}',
  headers: [
    { key: 'Authorization', value: 'Bearer {{API_TOKEN}}', enabled: true },
    { key: 'X-Debug', value: '{{DEBUG}}', enabled: true }
  ]
});
With these environment variables: 
API_URL = https://api.example.com
API_VERSION = v2
USER_ID = 123
API_TOKEN = sk_live_xxxxx
DEBUG = true
The request becomes: 
GET https://api.example.com/v2/users/123
Headers:
  Authorization: Bearer sk_live_xxxxx
  X-Debug: true

​
Interpolation syntax

Yasumu supports multiple interpolation patterns: 
// Looks in variables first, then secrets
{{API_URL}}
{{TOKEN}}

​
Manual interpolation

const env = await workspace.environments.getActiveEnvironment();

// Interpolate a string
const template = 'API URL: {{API_URL}}, Version: {{API_VERSION}}';
const result = env.interpolate(template);

console.log(result);
// Output: "API URL: https://api.example.com, Version: v2"

// With prefixed syntax
const secret = env.interpolate('Token: {{secrets.API_TOKEN}}');
console.log(secret);
// Output: "Token: sk_live_xxxxx"

​
Environment best practices

​
Separate concerns

Create distinct environments for each stage: 
// Development
await workspace.environments.create({
  name: 'Development',
  variables: [
    { key: 'API_URL', value: 'http://localhost:3000', enabled: true },
    { key: 'DEBUG', value: 'true', enabled: true }
  ]
});

// Staging
await workspace.environments.create({
  name: 'Staging',
  variables: [
    { key: 'API_URL', value: 'https://staging.example.com', enabled: true },
    { key: 'DEBUG', value: 'false', enabled: true }
  ]
});

// Production
await workspace.environments.create({
  name: 'Production',
  variables: [
    { key: 'API_URL', value: 'https://api.example.com', enabled: true },
    { key: 'DEBUG', value: 'false', enabled: true }
  ]
});

​
Security considerations

  • Use secrets for sensitive data: API keys, tokens, passwords should always be stored as secrets
  • Don’t commit secrets: Secrets in .ysl files should be empty in version control
  • Local configuration: Team members set their own secret values locally
  • Rotate credentials: Regularly update API tokens and passwords

​
Naming conventions

// Use UPPER_SNAKE_CASE for variables
API_URL
API_TOKEN
MAX_RETRIES
TIMEOUT_MS

// Be descriptive
PROD_DATABASE_URL        // Good
DB                       // Too vague

OAUTH_CLIENT_SECRET      // Good
SECRET                   // Too generic

​
Toggle instead of delete

// Instead of deleting, disable variables
await env.variables.set('OLD_FEATURE_FLAG', 'false', false); // disabled

// This preserves the value for reference
const old = env.variables.getRaw('OLD_FEATURE_FLAG');
console.log(old?.value); // Still accessible

​
Common patterns

​
Base URL configuration

// Environment variables
API_URL = https://api.example.com
API_VERSION = v2

// In requests
url: '{{API_URL}}/{{API_VERSION}}/users'
// Results in: https://api.example.com/v2/users

​
Dynamic authentication

// Store token in secret
await env.secrets.set('AUTH_TOKEN', 'Bearer sk_live_xxxxx');

// Use in request
headers: [
  { key: 'Authorization', value: '{{AUTH_TOKEN}}', enabled: true }
]

​
Feature flags

// Environment-specific features
await env.variables.set('ENABLE_CACHE', 'true');
await env.variables.set('ENABLE_LOGGING', 'true');
await env.variables.set('MOCK_RESPONSES', 'false');

​
Troubleshooting

​
Variable not interpolating

// Check if environment is active
const active = await workspace.environments.getActiveEnvironment();
if (!active) {
  console.log('No active environment!');
}

// Check if variable exists and is enabled
const value = active.variables.get('MY_VAR');
if (!value) {
  console.log('Variable not found or disabled');
}

​
Variable shows {{VAR_NAME}} in response

This means the variable wasn’t found. Check:
  1. Variable name spelling
  2. Variable is enabled
  3. Environment is active
  4. Variable exists in current environment

​
Next steps

REST requests

Use variables in HTTP requests

Team collaboration

Share environments with your team

Build docs developers (and LLMs) love

Get started for freeTalk to us