Variables

Variables let you define a value once and reuse it across requests. Open Environments in the header (the sliders icon next to the environment picker) to edit them in a table.

Scopes and precedence

When a name is defined in more than one place, the most specific scope wins. From lowest to highest:

Values written by Extract rules and scripts (env.set) are saved into the active environment, so they take part as environment variables.

The Go engine, the desktop and web apps and the CLI resolve a name the same way, apart from global environments, which exist in the apps only.

The environment table

Each environment is a table of rows: a name, a value, an on/off switch and a lock.

• Secret (lock): the value is masked in the table (the eye reveals it) and in hover previews and suggestions. It is never written to the workspace YAML, to exports or to share links. See Secret variables.
• Colour: a label shown next to the environment picker, so production is hard to mistake for staging.
• Inherits from: the environment whose variables are used first. Cycles are not offered.
• Duplicate, Delete and Filter variables (matches names and the values of non-secret rows).

Names may contain letters of any script, digits, underscores, dots and hyphens. Values can be strings, numbers or booleans; a value of null is treated as undefined.

Using variables

Write {{name}} wherever the value should appear: URL, query parameters and headers (keys and values), body (including form and multipart text fields), auth fields, GraphQL query and variables, and WebSocket URL and headers.

• Names are case-sensitive and whitespace inside the braces is ignored: {{ name }} is {{name}}.
• A placeholder with no matching variable is left as written, so the mistake is visible in the request that goes out.
• Every occurrence is replaced. Values are inserted as they are; a value placed in a URL is not percent-encoded apart from spaces.
• Placeholders are not expanded recursively.
• In fields with variable support, defined names are underlined, hovering shows the value (masked for secrets) and the scope it came from, and typing {{ offers completions.

Secret variables

Mark a row as secret with its lock.

• Desktop: values live in the operating system keychain (Windows Credential Manager, macOS Keychain, the Secret Service on Linux). If no keychain is available they are kept in secrets.enc in the app data folder, encrypted with AES-256-GCM using a key file next to it. That fallback protects against casual reading and accidental sharing, not against someone who can read both files.
• Only the name of a secret variable is written to the environment file (as meta), never its value. Copying a workspace folder to another computer therefore leaves the secret values behind.
• Web: there is no keychain in a browser, so values stay in the browser's local storage and are still left out of exports and share links.
• CLI: provide the value yourself, for example gostman run <collection> --var-from-env API_TOKEN (the environment variable name becomes the variable name) or --var token=value.

Secret managers

A variable can read its value from HashiCorp Vault, AWS Secrets Manager, Azure Key Vault or Google Cloud Secret Manager. In the environment table choose the key icon on a row, pick a connection and give the secret path, an optional JSON field and an optional version. Test reads the secret and shows only that it worked and how many characters it has.

• The collection stores only the reference. Connections (address, namespace, sign-in) are settings of this computer under Secret managers, with credentials in the keychain, so a cloned collection cannot point your credentials at its own server. An unknown connection name fails with a message.
• References are resolved when a request is sent and cached in memory for five minutes. Values are never saved, exported or shared. If a reference cannot be read the request is not sent.
• Folders that are not trusted yet never resolve references.
• Desktop app and CLI only. See the README for the CLI variables, --secrets and --secrets-env-file.

Dynamic variables

Dynamic variables are generated by the engine every time a request is sent, so each occurrence gets its own value. They are the same in the apps and the CLI.

A variable you define with the same name takes precedence. The code snippet view and the request that is actually sent each generate their own values.

Prompt variables

{{?name}} asks for a value when the request is sent. A dialog lists every prompted name found in the request, pre-filled with a variable of the same name if one exists. Cancelling the dialog stops the send. The values are not saved.

In the CLI, --var name=value (or --var-from-env) supplies the value; without one the placeholder is left as written. Runs from the runner dialog do not prompt.

.env files

In a folder workspace, a .env file next to gostman.yaml is read as process environment variables and exposed as {{process.env.NAME}}. Lines look like NAME=value, export NAME=value or NAME="quoted value"; # starts a comment. The file is listed read-only in the Environments dialog (values masked), is never written back and never exported. gostman run on a workspace folder reads it too. Other operating system variables are not exposed; pass them with --var-from-env.

Setting variables from a response

The Extract tab stores rules on a request. After each response, every enabled rule copies a value into the active environment:

Where substitution happens

Substitution is done by the Go engine in engine/ when the request is prepared, identically for the desktop app, the web version and the CLI. Scope resolution runs in the frontend for the apps and in runner/variables.go for the CLI.