Environments - Auk Documentation

Environments allow you to group variables that can be referenced throughout Auk when sending requests or using scripts. They’re essential for managing different configurations like development, staging, and production.

What are Environments?

An environment is a set of key-value pairs that can be used across your workspace. Instead of hardcoding values in requests, you reference variables that change based on the active environment. Example:

Development Environment:
- API_URL = http://localhost:3000
- API_KEY = dev_key_123

Production Environment:
- API_URL = https://api.example.com
- API_KEY = prod_key_xyz

Request URL:

<<API_URL>>/users

When you switch environments, the same request automatically uses different values.

Types of Environments

Global Environment

Variables accessible from any workspace:

Scope: All workspaces
Use Case: Common values used everywhere
Examples: Default timeouts, common headers
Storage: Stored in app settings, not workspace

When to Use:

Values that never change across projects
Personal preferences
System-wide defaults

Workspace Environments

Variables specific to a workspace:

Scope: Current workspace only
Use Case: Project-specific configurations
Examples: API URLs, authentication tokens
Storage: Stored in workspace directory
Git Sync: Synced to Git repository (except secrets)

When to Use:

Project-specific values
Environment-specific configurations
Team-shared variables

Types of Variables

Regular Variables

Standard variables visible to everyone:

Visibility: Visible in UI
Git Sync: Synced to repository
Use Case: Non-sensitive configuration
Examples: URLs, timeouts, feature flags

Example:

{
  "API_URL": "https://api.example.com",
  "API_VERSION": "v1",
  "TIMEOUT": "30000"
}

Secret Variables

Sensitive variables that are never synced:

Visibility: Masked with asterisks (***)
Git Sync: Never synced to repository
Use Case: Sensitive data
Examples: API keys, passwords, tokens

Example:

{
  "API_KEY": "***",
  "DB_PASSWORD": "***",
  "AUTH_TOKEN": "***"
}

Secret variables are stored locally only. Each team member must set their own secret values. They are never committed to Git.

Variable Values

Each variable can have two types of values:

Initial Value

The default value when environment is created
Used when environment is first loaded
Synced to Git (for regular variables)
Shared with team

Current Value

The active value during your session
Can be modified at runtime
Not synced to Git
Temporary changes

Use Case:

Initial: API_URL = https://api.example.com
Current: API_URL = http://localhost:3000 (for local testing)

Creating Environments

Create New Environment

Click “Environments” icon in sidebar
Click “Add new” button
Enter environment name (e.g., “Development”)
Optionally add description
Click “Create”

Add Variables

Open the environment
Click “Add variable”
Enter key and value
Choose variable type (Regular or Secret)
Click “Save”

Example Environment:

Name: Development
Description: Local development environment

Variables:
- API_URL = http://localhost:3000 (Regular)
- API_VERSION = v1 (Regular)
- API_KEY = dev_key_123 (Secret)
- DEBUG = true (Regular)

Using Variables

In Requests

Reference variables using double angle brackets: URL:

<<API_URL>>/<<API_VERSION>>/users

Headers:

Authorization: Bearer <<AUTH_TOKEN>>
X-API-Key: <<API_KEY>>

Body:

{
  "apiUrl": "<<API_URL>>",
  "version": "<<API_VERSION>>"
}

Query Parameters:

?api_key=<<API_KEY>>&debug=<<DEBUG>>

In Scripts

Access variables in pre-request and test scripts: Get Variable:

const apiUrl = pw.env.get("API_URL");
const apiKey = pw.env.get("API_KEY");

Set Variable:

pw.env.set("AUTH_TOKEN", "new_token_123");
pw.env.set("USER_ID", "12345");

Delete Variable:

pw.env.unset("TEMP_VAR");

Check if Variable Exists:

if (pw.env.has("API_KEY")) {
  // Use API key
}

Switching Environments

Active Environment

Only one environment can be active at a time:

Click environment selector in top bar
Select environment from dropdown
All requests now use that environment’s variables

Keyboard Shortcut:

Cmd/Ctrl + E - Open environment selector

Quick Switch

Switch between frequently used environments:

Development ↔ Staging ↔ Production
Use keyboard shortcuts for faster switching
Environment indicator shows active environment

Managing Environments

Edit Environment

Right-click on environment
Select “Edit”
Update name, description, or variables
Click “Save”

Duplicate Environment

Create a copy of an environment:

Right-click on environment
Select “Duplicate”
A copy is created with ”- Copy” suffix
Rename and modify as needed

Secret variable values are not copied when duplicating. You must re-enter secret values in the duplicated environment.

Delete Environment

Right-click on environment
Select “Delete”
Confirm deletion

Deleted environments cannot be recovered unless you have Git history or backups.

Environment Organization

Common Environments

By Deployment Stage:

- Development
- Staging
- Production

By Feature:

- Feature-A
- Feature-B
- Main

By Region:

- US-East
- US-West
- EU-Central
- Asia-Pacific

By Client:

- Client-A
- Client-B
- Internal

Naming Conventions

Use clear, descriptive names:

✅ Good:
- "Development"
- "Production - US"
- "Staging - EU"

❌ Bad:
- "Env 1"
- "Test"
- "New Environment"

Git Sync Integration

What Gets Synced

Synced to Git:

Environment names and descriptions
Regular variable keys and values
Initial values
Environment structure

Not Synced:

Secret variable values
Current values (temporary changes)
Active environment selection

Team Collaboration

When working with a team:

Regular Variables: Shared via Git
- Everyone sees same values
- Changes synced automatically
- Version controlled
Secret Variables: Set individually
- Each team member sets their own
- Not shared via Git
- Documented in README

Example README:

## Environment Setup

### Required Secret Variables

Development:
- API_KEY: Get from team lead
- DB_PASSWORD: Use your local database password

Production:
- API_KEY: Get from AWS Secrets Manager
- DB_PASSWORD: Get from 1Password vault

Conflict Resolution

If multiple team members edit the same environment:

Auk detects conflicts during sync
Shows conflict resolution dialog
Choose resolution strategy
Merge changes

Learn more about conflict resolution

Advanced Features

Dynamic Variables

Set variables dynamically in scripts: Generate Timestamp:

const timestamp = Date.now();
pw.env.set("TIMESTAMP", timestamp);

Generate UUID:

const uuid = crypto.randomUUID();
pw.env.set("REQUEST_ID", uuid);

Extract from Response:

// In test script
const token = pw.response.body.token;
pw.env.set("AUTH_TOKEN", token);

Variable Precedence

When multiple variables have the same name:

Current Value (highest priority)
Initial Value
Collection Variable
Global Variable (lowest priority)

Example:

Global: API_URL = https://api.example.com
Environment: API_URL = http://localhost:3000
Collection: API_URL = http://staging.example.com

Active: http://localhost:3000 (Environment wins)

Conditional Variables

Use different values based on conditions:

// Pre-request script
const env = pw.env.get("ENVIRONMENT");

if (env === "production") {
  pw.env.set("API_URL", "https://api.example.com");
} else {
  pw.env.set("API_URL", "http://localhost:3000");
}

Variable Templates

Create template environments:

Create “Template” environment
Add all required variables with placeholder values
Duplicate for new environments
Fill in actual values

Template Example:

Name: Environment Template

Variables:
- API_URL = <REPLACE_WITH_URL>
- API_KEY = <REPLACE_WITH_KEY>
- TIMEOUT = 30000
- DEBUG = false

Import and Export

Export Environment

Right-click on environment
Select “Export”
Choose format (JSON)
Save file

Use Cases:

Backup
Share with team (without Git)
Migrate to another workspace

Import Environment

Click “Import” in environments section
Select environment file
Choose import options:
- Replace existing
- Merge with existing
- Create new
Click “Import”

Exported environments do not include secret variable values for security reasons.

Best Practices

Security

Protect Secrets:

Always use secret variables for sensitive data
Never commit secrets to Git
Document required secrets in README
Use password managers for team secrets

Example .gitignore:

# Never commit these
*.secret.json
secrets/
.env

Organization

Consistent Structure:

Use same variable names across environments
Document variable purposes
Keep environments up to date
Remove unused variables

Variable Naming:

✅ Good:
- API_URL
- AUTH_TOKEN
- DB_HOST

❌ Bad:
- url
- token
- host

Documentation

Document your environments:

## Environments

### Development
- API_URL: Local development server
- API_KEY: Development API key (get from team lead)
- DEBUG: Enable debug logging

### Production
- API_URL: Production API server
- API_KEY: Production API key (get from AWS Secrets Manager)
- DEBUG: Disable debug logging

Testing

Test with different environments:

Create test environment
Use test data
Verify requests work
Switch to production when ready

Troubleshooting

Variable Not Resolving

Problem: <<VARIABLE>> appears in request instead of value Solutions:

Check variable name spelling
Verify environment is active
Check variable exists in active environment
Ensure no typos in angle brackets

Secret Variable Empty

Problem: Secret variable has no value Solutions:

Secret values are not synced - set manually
Check if you’re in correct environment
Re-enter secret value
Verify variable type is “Secret”

Environment Not Syncing

Problem: Environment changes not appearing for team Solutions:

Check Git sync is enabled
Verify changes are committed
Push changes to remote
Team members need to pull changes
Remember: secrets don’t sync

Conflicts After Sync

Problem: Environment conflicts after Git sync Solutions:

Review conflict resolution dialog
Choose appropriate resolution strategy
Manually merge if needed
Test after resolution

Next Steps

Variables

Learn more about variables

Scripts

Use variables in scripts

Collections

Organize requests in collections

Git Sync

Sync environments with Git

Getting Started

Core Concepts

Workspace Management

Git Sync

API Testing

Features

Data Management

Desktop Client

​What are Environments?

​Types of Environments

​Global Environment

​Workspace Environments

​Types of Variables

​Regular Variables

​Secret Variables

​Variable Values

​Initial Value

​Current Value

​Creating Environments

​Create New Environment

​Add Variables

​Using Variables

​In Requests

​In Scripts

​Switching Environments

​Active Environment

​Quick Switch

​Managing Environments

​Edit Environment

​Duplicate Environment

​Delete Environment

​Environment Organization

​Common Environments

​Naming Conventions

​Git Sync Integration

​What Gets Synced

​Team Collaboration

​Conflict Resolution

​Advanced Features

​Dynamic Variables

​Variable Precedence

​Conditional Variables

​Variable Templates

​Import and Export

​Export Environment

​Import Environment

​Best Practices

​Security

​Organization

​Documentation

​Testing

​Troubleshooting

​Variable Not Resolving

​Secret Variable Empty

​Environment Not Syncing

​Conflicts After Sync

​Next Steps

Variables

Scripts

Collections

Git Sync

What are Environments?

Types of Environments

Global Environment

Workspace Environments

Types of Variables

Regular Variables

Secret Variables

Variable Values

Initial Value

Current Value

Creating Environments

Create New Environment

Add Variables

Using Variables

In Requests

In Scripts

Switching Environments

Active Environment

Quick Switch

Managing Environments

Edit Environment

Duplicate Environment

Delete Environment

Environment Organization

Common Environments

Naming Conventions

Git Sync Integration

What Gets Synced

Team Collaboration

Conflict Resolution

Advanced Features

Dynamic Variables

Variable Precedence

Conditional Variables

Variable Templates

Import and Export

Export Environment

Import Environment

Best Practices

Security

Organization

Documentation

Testing

Troubleshooting

Variable Not Resolving

Secret Variable Empty

Environment Not Syncing

Conflicts After Sync

Next Steps