Postman CLI environment commands `(postman environment)`

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.

When you use postman environment new, list, get, or var set with an environment in a Postman Cloud workspace, they accept the guest session that postman init creates, so you can run them without signing in first. You can also sign in with the postman login command or pass an --api-key. To learn more, see postman signup.

`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. Secret variable values are always masked in the output, with no option to reveal them.

Usage

postman environment get <environment> [options]

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

Options

--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 delete`

Permanently deletes an environment. Specify a cloud environment by its ID, or a local environment by its file path. The command prompts for confirmation unless you pass --yes.

Usage

postman environment delete <environment> [options]

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

Options

-y, --yes

Skips the confirmation prompt.

--verbose

Shows verbose output.

--json

Prints the result as JSON for machine-readable output.

Examples

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

`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. Optional only when you pass --secret-id, which links the variable to a Shared Vault secret instead of an inline value.

Options

-e, --environment <environment>

Required

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

--secret-id <id>

Links this variable to a Shared Vault secret instead of an inline value. Use the secret ID from postman secret create’s output.

--vault-id <id>

The vault ID for --secret-id. Auto-resolved from --workspace when --secret-id is given without it. To set it explicitly, get it from postman secret list’s output.

-w, --workspace <workspaceId>

The workspace to resolve --vault-id from, when you pass --secret-id without --vault-id. Falls back to .postman/resources.yaml.

--verbose

Prints more request and debug details.

--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 set apiToken --secret-id b8748ab8-d1bb-477f-95e2-78625adea75f \
  --environment 123456-11111111-2222-3333-4444-555555555555 --workspace 12345678-90ab-cdef-1234-567890abcdef

`postman environment var get`

Reads the value of a single variable from an environment. If the variable is a secret, its value is always masked in the output, with no option to reveal it.

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.

--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

`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