Postman CLI workspace commands (postman workspace)
Postman CLI workspace commands (postman workspace)
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.
In an interactive terminal, the command prompts you to show more results. In a non-interactive context, such as CI/CD, it stops after the first page and prints a cursor to pass to --cursor for the next page.
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.
A pagination cursor from a previous page’s response. Use it to fetch the next page of results.
Show detailed logging information.
Show debug output.
Return the results in JSON format.
Examples
postman workspace get
Reads a single workspace’s metadata, such as its visibility, the team that owns it, and its timestamps. Specify the workspace by its ID, which you can find with postman workspace list. Pass --elements to also report a count of the resources the workspace holds. This command is read-only.
To use this command, sign in to Postman with the postman login command.
Usage
The ID of the workspace to read. Find it with postman workspace list.
Options
Also reports a count of the resources the workspace holds, such as collections, environments, and monitors.
Prints the workspace as JSON for machine-readable output, instead of a table.
The time to wait for the API before failing, in milliseconds.
Examples
postman workspace context
Reads everything a workspace holds, including its collections, environments, monitors, mocks, specifications, flows, and simulations, and how they relate. One call replaces a list command for each element type. Monitors are the only elements that carry relationships. Each monitor shows the collection and environment it runs, and each collection and environment shows the monitors that run it. Mocks, specifications, flows, and simulations are listed without relationships. Specify the workspace by its ID, or omit the ID to read the workspace bound to the current folder in .postman/resources.yaml. This command is read-only.
To read the workspace’s activity feed, use postman workspace activity, or pass --section activity.
To use this command, sign in to Postman with the postman login command, set the POSTMAN_API_KEY environment variable, or use the temporary session that postman init creates. Listing flows requires a signed-in session. With an API key alone, the flow section reports an error and the other sections still print.
Usage
The ID of the workspace to read. Defaults to the workspace bound to the current folder in .postman/resources.yaml. Find an ID with postman workspace list.
Output
The command prints one line for each item, with its name first and its ID last, grouped under a heading for each section. When the current folder is bound to the same workspace, each collection, environment, specification, flow, mock, and simulation also shows its local path, or cloud only when it has no local file. Monitors aren’t tracked locally, so they show neither. Each simulation shows its mock count and whether it’s deployed, with its URL when it is.
The command prints JSON when its output is piped, so a script doesn’t need to pass --json. Use --text to print the item lines even when the output is piped. The JSON carries a schemaVersion, the workspace, the counts for each section, the sections themselves, the local binding, and whether the read was partial. Each simulation item carries a simulation object with its status, url, and mocks count. The url is null until the simulation is deployed.
Options
The sections to show, as a comma-separated list. Accepts collection, environment, monitor, mock, spec, flow, simulation, and activity. Defaults to every section except activity. Counts are reported for every section other than activity, including the ones you don’t ask for.
The maximum number of items to return in each section, or the maximum number of entries for activity. A section that was cut reports how many items were left out, and keeps items that have relationships ahead of those that don’t.
Prints JSON for machine-readable output. This is already the default when the output is piped. You can’t combine --json with --text.
Prints the item lines even when the output is piped. You can’t combine --text with --json.
The time to wait for the API in each section’s listing, in milliseconds.
The following options apply only to the activity feed, so pass them with --section activity. The command accepts them without it, but ignores them and reports nothing about them.
Filters the feed to the given element types, as a comma-separated list, such as api,collection. A push is recorded as the workspacePush type. Filter to that type to see only pushes, including any note left with postman workspace push --message.
Filters the feed to the given users, as a comma-separated list of user IDs.
Returns the page of entries that follows this cursor. Use it with --limit to page through a long feed.
Asks the API for a human-readable description of each entry.
Prints one plain line for each entry, with the time, the person, and the message, and no header or table. It changes the output only when activity is the single section you ask for. Alongside other sections, the feed prints that way regardless.
Exit codes
Examples
postman workspace activity
Reads a workspace’s activity feed, which records who changed what in the workspace and when, along with the messages left on pushes. This command is shorthand for postman workspace context with --section activity. Specify the workspace by its ID, or omit the ID to read the workspace bound to the current folder in .postman/resources.yaml. You can filter the feed by element type or contributor, and page through a long feed with --cursor and --limit. This command is read-only.
To use this command, sign in to Postman with the postman login command, set the POSTMAN_API_KEY environment variable, or use the temporary session that postman init creates.
Usage
The ID of the workspace to read. Defaults to the workspace bound to the current folder in .postman/resources.yaml. Find an ID with postman workspace list.
Options
Filters the feed to the given element types, as a comma-separated list, such as api,collection. A push is recorded as the workspacePush type. Filter to that type to see only pushes, including any note left with postman workspace push --message.
Filters the feed to the given users, as a comma-separated list of user IDs.
Returns the page of entries that follows this cursor. Use it with --limit to page through a long feed.
The maximum number of entries to return.
Asks the API for a human-readable description of each entry.
Prints the feed as JSON for machine-readable output, instead of a table.
Prints one plain line for each entry, with the time, the person, and the message, and no header or table. Prints nothing when there are no entries. Use it to paste the feed into a prompt or a log. You can’t combine --brief with --json.
The time to wait for the API before failing, in milliseconds.
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.
Prints the result as JSON for machine-readable output.
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 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.
Applies safe automatic fixes to repairable workspace lint issues, including a path in .postman/resources.yaml whose folder or file has moved. It lists any path it couldn’t repair, with the reason.
Examples
Learn more at Native Git workflows.
postman workspace create
This command creates a Postman workspace and connects it to your local Git repository, so you can push to it and pull from it. By default, it names the workspace after your Git remote and connects the current directory. To create a workspace without connecting it, use the --no-connect option. To connect an existing workspace instead of creating one, use postman workspace connect-git.
To use this command, sign in to Postman with the postman login command, or run it in the temporary session that postman init starts. A temporary session owns the team it was given, so new workspaces are created in that team. Run postman signup to claim the account and keep them. An earlier temporary session, or one that has expired, can’t own a workspace, so run postman init to start a fresh one.
Usage
Options
The workspace’s visibility.
The name for the workspace. Defaults to the owner/repo from your Git remote.
An optional summary for the workspace.
The team in your organization that the workspace belongs to. Required for a team workspace when your organization has teams. Find it with postman team list.
What a team or public workspace grants. Applies to the team named by --team-id, or to your whole organization when none is named. Defaults to your team’s configured default.
The directory to connect to the workspace. Defaults to the current directory.
Create the workspace without connecting it to the repository.
Create the workspace even when one is already recorded for this repository.
Prints the result as JSON for machine-readable output.
Examples
Learn more at Native Git workflows.
postman workspace delete
This command permanently deletes a workspace and its contents. Specify the workspace by its ID, which you can find with postman workspace list. The ID is required.
In an interactive terminal, the command prompts you to confirm before it deletes. In a non-interactive context, such as CI/CD, it doesn’t delete unless you pass --yes.
Deleting a workspace is permanent and removes everything the workspace holds, such as collections, environments, and mocks. This can’t be undone.
To use this command, sign in to Postman with the postman login command.
Usage
The ID of the workspace to delete. Find it with postman workspace list.
Options
Prints the outcome as JSON for machine-readable output.
The time to wait for the API before failing, in milliseconds.
Show detailed logging information.
Skips the confirmation prompt. Required to delete in a non-interactive context, such as CI/CD.
Examples
postman workspace connect-git
This command connects a Postman workspace to a local Git repository. It registers the current directory’s Git remote with the workspace and writes the .postman/resources.yaml claim file. Connecting a workspace is a prerequisite for the postman workspace pull and postman workspace push commands.
You can connect a workspace to a subfolder of a repository, so one repository can back several workspaces.
Usage
The ID of the Postman workspace to connect.
The path to the folder to connect. Defaults to the current directory. A folder below the repository root connects to that subdirectory.
Options
Show detailed logging information.
Prints the result as JSON for machine-readable output.
Examples
Learn more at Native Git workflows.
postman workspace disconnect-git
This command disconnects a Postman workspace from its local Git repository. It disconnects the workspace in Postman and clears the connection in .postman/resources.yaml. No local files are deleted. If you omit the workspace ID, the command disconnects the workspace that the current folder is connected to.
Use this command to undo a postman workspace connect-git connection, or to clear a stale connection before you connect a different workspace.
Usage
The ID of the workspace to disconnect. If omitted, the command disconnects the workspace connected to the current folder.
Options
Show detailed logging information.
Skips the confirmation prompt. Use it to disconnect in a non-interactive context, such as CI/CD.
Prints the result as JSON for machine-readable output.
Examples
Learn more at Native Git workflows.
postman workspace pull
This command pulls workspace elements (such as collections, environments, specifications, and flows) from a Postman workspace into your local Git-native folder. Use it to bring cloud changes into your local repository.
To use this command, sign in to Postman with the postman login command.
Usage
The ID of the workspace to pull from. If omitted, the command pulls from the workspace connected to the current directory’s Git remote.
Options
Pull from a different source workspace.
Show detailed logging information.
Skip all confirmation prompts.
Prints the result as JSON for machine-readable output.
Flows
Pulled flows are written to postman/flows/. The CLI rewrites each flow’s references to environments, saved requests, and other flows so they point to local files, which makes a pulled flow usable without further edits.
When a flow calls another flow with a Flow block, the CLI pulls the referenced flow even when you haven’t selected it. Flows are written as a flat set of local files, without the folders you may have grouped them into in the Postman Cloud.
Examples
Learn more at Native Git workflows.
postman workspace diff
Previews the differences between your local workspace and its Postman Cloud counterpart, so you can review drift before you push. This command is read-only. You can also use it as a CI gate with --exit-code.
Usage
The ID of the cloud workspace to compare against. Defaults to the one linked to your local workspace.
Options
The push strategy to preview. With force-sync, the diff also shows cloud elements that would be deleted. Use default to preview a create-and-update-only push, which hides deletions.
Skips the content comparison. This is faster, but it lists updated elements without checking whether their content changed.
Returns a failure exit code when the diff finds drift. Useful as a CI gate.
Prints the diff as JSON for machine-readable output.
Prints detailed logging.
Stops the run after this many milliseconds.
Examples
postman workspace push
This command pushes local changes for collections, environments, specifications, and other workspace elements (like SDKs, code mocks, simulations, flows, 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.
The command reports its events to the API Catalog and Application Inventory by default. To turn this off, pass --report-events=false.
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.
A short note on what changed, like a commit message, up to 500 characters. The note appears in the workspace’s activity feed, and the command records it only when the push changes something. If recording the note fails, the command warns you and the push still succeeds. With --json, an activityLog object reports whether the note was recorded and why not. To read the notes, run postman workspace activity, which prints them with the rest of the feed. Add --type workspacePush to see only pushes.
Show detailed logging information.
Events are reported to the API Catalog and Application Inventory by default, whether you pass --report-events. To turn reporting off, pass --report-events=false. You can also use --no-report-events.
Skip all confirmation prompts.
Prints the result as JSON for machine-readable output.
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.
In a monorepo with multiple services, connect each service’s workspace to that service’s folder rather than the repository root, and run this command from the service folder. The command then reads that service’s .postman/resources.yaml manifest and syncs only that service’s elements. To learn more, see Monorepos with multiple services.
Examples
Learn more at Native Git workflows.
postman workspace share
Grants a role on a workspace to one or more people.
To use this command, sign in with the postman login command or pass --api-key. A temporary session can’t share.
Usage
The ID of the workspace to share.
Options
Who to share with. You can repeat the option, and each value can be a comma-separated list. A value that contains @ is an email address. Any other value is a Postman user ID. You can share with up to 20 people at a time.
The role to grant.
Prints the result as machine-readable JSON.
The number of milliseconds to wait for Postman.
Your Postman API key. Defaults to your postman login session.