October 20, 2026

You can create a secret in Postman Shared Vault, link it to an environment variable, and use it in collection runs or standalone API requests without storing the plaintext value in your Collection or Environment. The entire workflow is available from the Postman CLI.

This closes an important gap in command-line API development. The Postman CLI could already resolve a Shared Vault secret at runtime, but creating the secret and linking it to a variable required setup in the Postman app or direct API calls. You can now complete the workflow from the terminal.

Postman CLI secret workflow at a glance

The workflow has four steps:

Create a secret with postman secret create.
Link the returned secret ID to an environment variable with postman environment var set.
Reference the variable with normal Postman syntax, such as {{PAYMENT_API_TOKEN}}.
Run a Collection or standalone request and let the CLI resolve the secret at runtime.

The Environment stores a reference to the Shared Vault secret rather than its plaintext value. The same reference works with cloud Environments identified by ID and local environment files stored with your project.

Demo summary: The accompanying video creates a disposable Shared Vault secret, links it to a cloud Environment, uses it in a standalone postman request, runs a Collection with the same Environment, and verifies the linked variable in the Postman app.

What is a Postman Shared Vault secret

A Postman Shared Vault secret is sensitive data, such as an API token, password, or client secret, stored in a workspace’s Shared Vault. Requests and scripts use the secret through a secure variable, and Postman applies the value when the request runs.

Keeping the value in the vault separates credentials from Collections, Environments, and other API artifacts. This makes it easier to reuse a credential without copying the plaintext value into multiple files or tools. Learn more in the Postman Vault documentation.

Prerequisites for creating a secret

Before starting, make sure you have:

A Postman CLI release later than or equal to 1.69.0.
An authenticated Postman CLI session created with postman login.
A Postman Workspace where you have permission to create Shared Vault secrets.
A cloud environment ID or a path to a local Postman environment file.

If your current directory was initialized with postman init, the CLI can read the workspace ID from .postman/resources.yaml. Otherwise, pass the workspace ID with --workspace.

Create a Postman Shared Vault secret

Start by naming the secret:

The CLI opens a one-time browser form where you enter the credential. Its output contains names and identifiers rather than the secret value. This also lets a coding agent initiate the workflow while you enter the value yourself.

To enter one secret through a masked terminal prompt instead, add –terminal:

Save the returned secret ID for the next step.

Create a secret from standard input

For a controlled provisioning or credential-rotation workflow, provide the value through standard input:

Use printf instead of echo when the value must not receive a trailing newline. Avoid placing the plaintext value directly in the command.

Creating secrets should normally be a provisioning or rotation step, not something every CI run repeats. Routine test and deployment jobs can reuse the linked environment variable.

Link the secret to an environment variable

Link the new secret to a variable with postman environment var set:

When --vault-id is omitted, the CLI uses the workspace to resolve the correct vault. If the project is already bound to a workspace, you can also omit --workspace.

The successful command confirms the link:

To link a secret in a local environment file, pass its path instead of a cloud environment ID:

In both cases, the variable contains the vault and secret identifiers required for runtime resolution. It does not contain a stored plaintext value.

For more information about reading and updating Environments, see the Postman CLI environment command reference.

Use the secret in a standalone Postman request

Reference the linked variable with the normal {{variableName}} syntax. For example, use it as a bearer token:

Before sending the request, the CLI identifies the vault-backed variable and resolves it:

This makes postman request useful for authenticated debugging, smoke tests, and automation without putting the token in the command itself.

The destination API still receives the resolved credential because it needs the value to authenticate the request. Prefer authorization fields or headers over query parameters, since URLs are commonly captured in server, proxy, browser, and observability logs. Also avoid scripts or verbose diagnostics that print sensitive request data.

Use the same secret in a Postman Collection

A Collection can reference the same variable in a URL, header, body, authorization field, or script:

Run the Collection with the linked Environment:

The Postman CLI resolves the Shared Vault secret before running the requests. The Collection can then run its tests and scripts without storing the token in the collection definition.

You can use the same approach in development, CI pipelines, and other automated collection workflows. See Working with the Postman CLI for installation, authentication, collection execution, and CI examples.

Verify the vault link in the Postman app

Open the Environment in the Postman app after linking the variable. The secure variable displays a Shared Vault reference instead of a plaintext environment value.

This gives the terminal and the Postman app a consistent model:

Postman Shared Vault owns the sensitive value.
The Environment owns the reusable variable name and vault reference.
Collections and requests use the variable name.
The Postman runtime resolves the value when the workflow runs.

The link can therefore be created through the CLI and inspected through the Postman app without copying the secret between interfaces.

Security recommendations for Postman CLI secrets

Use the following practices when adding this workflow to development or CI:

Enter values through the masked prompt or standard input. Don’t pass plaintext secrets as command-line arguments.
Store only secret references in Collections and Environments.
Use a dedicated provisioning or rotation job to create secrets instead of recreating them during every build.
Limit workspace and vault access to the people and automation that require it.
Send credentials only to intended API domains and prefer headers or authorization fields over URLs.
Review scripts, request logging, debug output, and target API behavior for places where a resolved value could be printed.
Treat local environment files containing vault IDs and secret IDs as configuration metadata, even though they don’t contain plaintext values.

Vault storage reduces the number of places where plaintext credentials are persisted. It does not prevent an authorized request, script, or destination API from receiving or logging a value after runtime resolution.

Benefits for API development teams

The command-line Shared Vault workflow helps teams:

Provision secrets without switching from the terminal to the Postman app.
Keep plaintext credentials out of collection and environment definitions.
Reuse one linked variable in standalone requests and full collection runs.
Apply the same secret configuration to local and cloud Environments.
Bootstrap development and CI environments through repeatable commands.
Inspect the resulting variable relationship in the Postman app.

The result is a clearer separation between API behavior, environment configuration, and credential storage.

Frequently asked questions

Can I create a Postman Vault secret from the command line

Yes. Use postman secret create <key> to create a secret in a workspace’s Postman Shared Vault. The value is collected through a masked interactive prompt or standard input.

Does the Postman CLI store the plaintext secret in the environment

No. When you link a Shared Vault secret with postman environment var set --secret-id, the Environment stores a vault reference containing identifiers for the secret and vault. The runtime retrieves the value when it runs the request or Collection.

Can I use a Shared Vault secret with postman request

Yes. Link the secret to an environment variable, reference that variable in the request with syntax such as {{PAYMENT_API_TOKEN}}, and pass the Environment with --environment.

Can I use the same secret in a collection run

Yes. Reference the linked variable in the Collection and run it with postman collection run <collection> --environment <environment>. The CLI resolves the vault-backed variable before running the Collection.

Do vault-linked variables work with local environment files

Yes. The linking command accepts either a cloud environment ID or a path to a local environment file. Runtime secret resolution works for both environment targets when the CLI has the required authentication and vault access.

How should CI provide a new secret value

Pass the value through standard input from the CI platform’s protected secret store. Use this as a deliberate provisioning or rotation operation. Routine CI jobs should use an existing linked Environment instead of creating a new vault secret on every run.

Can a resolved secret still appear in logs

Yes, if a request sends it in a URL, a script prints it, verbose diagnostics include sensitive fields, or the destination API echoes it. Vault linking prevents plaintext storage in Postman artifacts; it does not override the behavior of requests, scripts, loggers, or target systems.

Create once and use across Postman workflows

Postman CLI secrets provide an end-to-end terminal workflow for Shared Vault credentials. Create the secret, link it to an environment variable, and use the variable in both individual requests and complete collection runs.

This keeps the stored credential in Postman Shared Vault while giving developers and automation a familiar {{variableName}} interface across the Postman CLI and app.

To get started, authenticate with postman login, choose a Workspace and Environment, and create your first secret: