Environments

What is an environment

An environment is a named set of key-value string variables. Variables are expanded in request URLs, headers, body, and auth fields using the {{varname}} template syntax.

Environments allow the same collection to target different servers (dev, staging, production) without editing individual requests.

Template syntax

Wrap variable names in double curly braces:

{{base_url}}/api/v1/users
Authorization: Bearer {{api_token}}

Expansion happens at send time. If a variable is not defined in the active environment, the {{varname}} token is left unchanged in the request.

Expansion applies to:

• The URL field.
• Query parameter values.
• Header values.
• Body content (all body types).
• Auth field values (token, username, password, key value, etc.).

Variable precedence

When a collection defines a base_url field and the active environment also defines a base_url variable, the environment value wins. This lets you use the same collection across different environments:

• Collection base_url: https://api.example.com (default)
• Dev environment base_url: https://api.dev.example.com (override)

More generally, environment variables always override collection-level variables of the same name when expanding {{templates}}.

Creating an environment

In the GUI:

1. Open the Environments panel.
2. Click New Environment.
3. Enter a name (e.g. “dev”).
4. Add variables as key-value pairs in the table.
5. Click Save to overwrite the current file (a confirmation dialog appears), or click Save As to choose a new filename. If the environment has never been saved, Save behaves like Save As.

Deleting an environment

1. Load the environment you want to delete (select it from the toolbar combobox so it becomes the active environment).
2. Open the Environments editor (click “Environments” in the toolbar).
3. Click the Delete button.
4. Confirm deletion in the dialog that appears.

The JSON file is removed from disk, the environment is unloaded, and the toolbar combobox is refreshed.

Switching environments

The environment selector in the toolbar shows the active environment. Select a different environment from the dropdown to switch. The dropdown automatically expands to fit long environment names. Only one environment is active at a time.

When no environment is selected, no variable expansion occurs.

Saving and loading

Environments are saved as JSON files. Each file holds one environment.

Save: click Save to overwrite the current file, or Save As to choose a new filename. Load: click Load and select a JSON file.

JSON format

An environment file has this structure:

{
  "name": "dev",
  "color": "#5090FF",
  "variables": {
    "base_url": "https://api.dev.example.com",
    "api_token": "tok_abc123",
    "user_id": "42"
  }
}

The name field identifies the environment. The color field is optional – a #RRGGBB hex string that tints the UI when this environment is active. The variables object contains string key-value pairs. All values must be strings.

Using environments in CLI mode

Pass an environment file with the -e flag:

hook run -f collection.json -e dev.json
hook export -f collection.json -e dev.json

The environment variables are expanded in the request before execution or export.

Programmatic variable setting

Pre-request scripts can set variables at runtime using:

set_var("name", "value")

This updates the active environment for the current request and all subsequent requests in the same session. See Scripts for details.

Multiple environments

A typical setup has one environment file per target:

environments/
  dev.json
  staging.json
  production.json

Each file defines the same variable names with different values. Switching the active environment changes where requests are sent without modifying the collection.

Importing a directory of environments

To bulk-import an entire directory of Hook environment JSON files:

1. Click “Import Datas” in the toolbar.
2. Click “Import Environment Directory (.json)”.
3. Select the directory containing .json environment files.

Each valid environment file is copied into the environments/ data directory. The status label shows how many environments were imported. The toolbar combobox refreshes automatically.

Environment color

Each environment can have an optional color that provides a visual indicator of which environment is active. When set, the color appears as:

• A tinted accent on interactive widget borders (hover/active states).
• A colored border on the environment combobox in the toolbar.
• A color stripe at the left edge of the statusbar.

To set a color in the GUI, open the environment editor and use the color swatches or type a #RRGGBB hex value. Click X to clear the color. Environments without a color use the default theme accent.

In the JSON file, add a "color" field with a #RRGGBB value:

"color": "#DC503C"

This is useful for visually distinguishing production (red) from development (blue) environments.

Variable naming

Variable names are plain ASCII strings. Use underscores or hyphens as separators. Names are case-sensitive.

Good: base_url, api-token, userId Bad: names with spaces or special characters other than underscore and hyphen.