Workspace commands
This topic covers workspace management commands for the Postman CLI.
The Postman CLI includes workspace commands to list the workspaces you have access to and to validate, synchronize, and push local collections, environments, and specifications to Postman workspaces in the cloud. Add the commands to your CI/CD script to automate these tasks during the deployment process. Learn more about adding workspace commands to your CI/CD pipeline.
postman workspace list
This command lists all the Postman workspaces you have access to. Each entry shows the workspace’s ID, visibility type, and name. Use the filtering options to narrow the results by name.
To use this command, sign in to Postman with the postman login command.
Usage
Options
Filter the listed workspaces by name.
Filter the listed workspaces by visibility type: team, public, private, or personal.
Show detailed logging information.
Show debug output.
Return the results in JSON format.
Examples
postman workspace prepare
This command validates and prepares your local workspace elements, such as collections and environments, for pushing to a Postman workspace. It checks for valid UUIDs, regenerates IDs if needed, and ensures all items and responses have proper IDs. It doesn’t check for name conflicts between local and cloud elements. Those are detected during push.
Usage
Options
Show detailed logging information.
Configuration
The command expects a .postman/resources.yaml file in your working directory.
Element paths can be relative (resolved from .postman/) or absolute. Collections can be directories or .json files, and environments can be .yaml, .yml, or .json files.
Examples
Learn more at Native Git workflows.
postman workspace lint
This command lints your local Postman workspace so you can find and fix problems before you push. It checks two things in a single report:
- Workspace configuration — the
.postman/resources.yamlmanifest. - Every discovered element — the collections, specifications, environments, and globals in your workspace, both in-tree (under
postman/) and declared inresources.yaml.
Run the command from the root of your local workspace. It lints the current working directory and doesn’t take a path argument. To lint only the workspace configuration and skip per-element linting, use the --meta option.
To lint a single element type on its own, use that element’s lint command, such as postman collection lint, postman environment lint, or postman globals lint.
Usage
Options
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. Accepted values are error, warning, info, and hint.
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 an invalid workspace reaches the cloud, or fail a pull request check.
Specifies the format of the lint results printed to the terminal. Accepted values are cli (human-readable output), table (a human-readable table), and json. To save the results, redirect the output to a file, for example --output json > results.json.
Lint only the workspace configuration (.postman/resources.yaml) and skip per-element linting.
The workspace ID used to fetch governance rulesets. Defaults to the ID in .postman/resources.yaml.
Examples
Learn more at Native Git workflows.
postman workspace push
This command pushes local changes for collections, environments, specifications, and other workspace elements (such as SDKs, mocks, and documents) to your Postman workspace. It synchronizes your local files with the workspace in the Postman cloud, performing create, update, and delete operations as needed.
If a local element’s name matches an existing element in the workspace that it isn’t already mapped to, how Postman resolves the conflict depends on how you run the command:
- Interactive — Postman prompts you to update the existing element, keep both, or skip.
- Non-interactive (with
--yesor in CI/CD) — Postman resolves the conflict by name match. If exactly one existing element shares the name, Postman updates it. If more than one does, Postman skips the element.
To use this command, sign in to Postman with the postman login command.
Usage
Options
Skip the prepare step before pushing.
The push strategy to use. Accepts default or force-sync.
default— (Default) Synchronizes elements in your local Git repository with the Postman cloud. Creates and updates elements, but doesn’t delete them from the cloud if they’re missing locally.force-sync— Mirrors elements in your local Git repository to the cloud. In addition to creating and updating, deletes elements from the cloud that have no local counterpart.
Show detailed logging information.
Uploads a workspace push event to Postman for analytics. This records that the push occurred but doesn’t display results you can view in Postman.
Skip all confirmation prompts.
Workflow
When you run push, it performs these steps:
- Validate — Checks if the collections, environments, and specifications exist globally and in the target workspace.
- Prepare (unless
--no-prepare) — Runs prepare automatically if invalid or missing IDs are detected. - Lint — Checks the workspace configuration and each element for problems that can block the push.
- Sync — Creates and updates elements. With
--push-strategy force-sync, it also deletes elements from the Postman cloud to match your local state. - Update Local Files — After successful creation, updates local files with server-returned IDs.
Before it syncs, push lints your workspace, which affects the push in one of two ways:
- Workspace configuration errors in
.postman/resources.yamlblock the entire push. Fix the reported errors, then run the command again. - Element errors in a collection, environment, or globals file skip only the affected element. The rest of the push continues.
To check your workspace before you push, run postman workspace lint.
Push overwrites existing cloud elements with your local copies, even when their content hasn’t changed. Your local files are always the source of truth. The push summary counts the operations performed, not the number of elements whose content changed, so Updated can be higher than the number of elements you actually edited.
Configuration
This command reads the .postman/resources.yaml manifest from your working directory.
The .postman/workflows.yaml file stores the links and their settings for collections generated from specifications and specifications generated from a collection. When you run the postman workspace push command, it pushes the link, the link’s settings, and any changes to them to the cloud.
The postman workspace push command doesn’t sync changes between a specification and its linked collection. To apply changes from a specification to its collection or a collection to its specification, manually update the collection or specification.
The system creates the workflows.yaml file when:
- You pull a specification and its generated collection into Local View.
- When you pull a collection and its generated specification into Local View.
- When you generate a collection in Local View.
If the file already exists and you perform one of these actions in Local View, the system adds a new sync entry in the workflows.yaml file.
Workspace documents in postman/documents/ are included in push and pull operations alongside collections and environments. To scope which documents are synced outside of postman/documents/, add a localResources.documents entry in .postman/resources.yaml with the path to the file.
To sync a monorepo with multiple services from a single workspace, connect the workspace to the repository root. Register each service’s elements under localResources in the root .postman/resources.yaml file, using paths relative to the .postman/ directory. Then run this command from the repository root. To learn more, see how to sync a monorepo with multiple services.
Examples
Learn more at Native Git workflows.