Environment commands

This topic covers environment commands for the Postman CLI.

Environments let you group sets of variables that you can reuse and switch between in Postman. You can use environment commands to create environments, list your environments, read an environment, and set, read, or remove individual variables. You can also validate your local environment files before you push them to a Postman workspace. These commands work with local environment files and with cloud environments referenced by ID.

`postman environment new`

Creates an environment. In a local project, this command scaffolds a local environment file. To create the environment in a Postman Cloud workspace instead, pass --workspace.

Usage

postman environment new <name> [options]

<name>

The name for the new environment.

Options

-w, --workspace <workspaceId>

Creates the environment in a Postman Cloud workspace by ID, instead of scaffolding it locally. Required when the current directory isn’t a local project.

--force

By default, if an environment file already exists at the path, the command stops without overwriting it. Use --force to overwrite it.

--json

Prints the result as JSON for machine-readable output.

Examples

postman environment new "Staging"
postman environment new "Staging" --workspace 12345678-90ab-cdef-1234-567890abcdef

`postman environment list`

Lists the environments in a Postman workspace. By default, it lists the environment files in the current directory’s workspace. Pass a path to a different local project directory, or use --workspace to list a cloud workspace’s environments instead.

Usage

postman environment list [workspacePath] [options]

[workspacePath]

Path to a local project directory (the folder that contains your postman/ directory). Defaults to the current directory. To list a cloud workspace’s environments instead, use --workspace.

Options

-w, --workspace <workspaceId>

The ID of the Postman workspace to list environments from.

-f, --filter <name>

Filters the results to environments whose name matches the given value.

--json

Prints the results as JSON for machine-readable output.

Examples

postman environment list --workspace 12345678-90ab-cdef-1234-567890abcdef
postman environment list ./my-postman-workspace

`postman environment get`

Reads an environment and prints its variables. Read a cloud environment by ID or a local environment file by path.

Usage

postman environment get <environment> [options]

The ID of a cloud environment or the path to a local environment file.

Options

--show-secrets

Includes secret variable values in the output. By default, secret values are hidden. To reveal a value stored in a Postman Shared Vault, you must be signed in with the postman login command or the POSTMAN_API_KEY environment variable.

--json

Prints the environment as JSON for machine-readable output.

--verbose

Prints more request and debug details.

Examples

postman environment get ./postman/environments/dev.environment.yaml
postman environment get 12345678-90ab-cdef-1234-567890abcdef

`postman environment var set`

Sets a variable in an environment, creating it if it doesn’t already exist. Works on a cloud environment by ID or a local environment file by path.

Usage

postman environment var set <key> <value> [options]

<key>

The name of the variable to set.

<value>

The value to assign to the variable.

Options

-e, --environment <environment>

Required

The ID of a cloud environment or the path to a local environment file.

--json

Prints the result as JSON for machine-readable output.

Examples

postman environment var set baseUrl https://api.example.com --environment ./postman/environments/dev.environment.yaml

`postman environment var get`

Reads the value of a single variable from an environment.

Usage

postman environment var get <key> [options]

<key>

The name of the variable to read.

Options

-e, --environment <environment>

Required

The ID of a cloud environment or the path to a local environment file.

--show-secrets

Shows the variable’s value if it’s a secret, instead of masking it. To reveal a value stored in a shared vault, you must be signed in with the postman login command or the POSTMAN_API_KEY environment variable.

--json

Prints the result as JSON for machine-readable output.

--verbose

Prints more request and debug details.

Examples

postman environment var get baseUrl --environment ./postman/environments/dev.environment.yaml
postman environment var get token --environment 12345678-90ab-cdef-1234-567890abcdef --show-secrets

`postman environment var unset`

Removes a variable from an environment.

Usage

postman environment var unset <key> [options]

<key>

The name of the variable to remove.

Options

-e, --environment <environment>

Required

The ID of a cloud environment or the path to a local environment file.

--json

Prints the result as JSON for machine-readable output.

--verbose

Prints more request and debug details.

Examples

postman environment var unset token --environment ./postman/environments/dev.environment.yaml

`postman environment lint`

This command checks that a local environment file is valid YAML and has the expected structure, field types, and required fields.

Usage

postman environment lint <path> [options]

<path>

Path to a Postman environment file or directory to lint.

Options

-o, --output <format>

Defaults to cli

Specifies the format of the lint results printed to the terminal. Accepted values are cli (human-readable output), table (a human-readable table), json, and csv. Results print to the terminal rather than saving to a file. To save the results, redirect the output to a file, for example --output json > results.json.

-f, --fail-severity <level>

Defaults to error

The command always lints everything and reports all issues. This option only sets the exit code, returning a failure code if any diagnostics are at this severity level or higher.

With error, the command returns a failure code only if errors are present. With warning, it returns a failure code whether warnings or errors are present. The failure code matters most in CI/CD, where it can stop the pipeline before invalid entities reach the cloud, or fail a pull request check.

Examples

postman environment lint ./postman/environments
postman environment lint ./postman/environments/Production.environment.yaml --fail-severity warning
postman environment lint ./postman/environments/Production.environment.yaml --output json