postman-cli

Reference knowledge for the Postman CLI and git sync file structure. This skill provides context used by the CLI commands.

Postman CLI Overview

The Postman CLI (postman-cli) is the official command-line tool for Postman. It runs collections, validates API specs, sends requests, and integrates with CI/CD pipelines.

Installation and Auth

npm install -g postman-cli
postman login

Authentication requires a valid Postman API key. Run postman login and follow the prompts.

Core Commands

Command	Purpose
postman collection run <id>	Run collection tests by cloud ID
postman request <METHOD> <URL>	Send an HTTP request
postman spec lint <file>	Validate an OpenAPI spec
postman context instructions	Get agent workflow instructions for API discovery and code generation
postman context collection get -c <id>	Get a collection's structure (folders, requests)
postman context request context -c <id> -r <id>	Get full request context for code generation
postman login	Authenticate with Postman

---

Git Sync File Structure

When a Postman workspace is connected to a git repo, it syncs using this structure:

project-root/
├── .postman/
│   └── resources.yaml              # Maps local paths → cloud IDs
├── postman/
│   ├── collections/
│   │   └── My API/                  # Collection (v3 folder format)
│   │       ├── .resources/
│   │       │   └── definition.yaml  # schemaVersion: "3.0", name
│   │       ├── Get Users.request.yaml
│   │       ├── Create User.request.yaml
│   │       └── Auth/               # Subfolder
│   │           └── Login.request.yaml
│   ├── environments/
│   │   └── dev.postman_environment.json
│   └── specs/
│       └── openapi.yaml

resources.yaml

Maps local collection/environment paths to their Postman cloud IDs:

cloudResources:
  collections:
    ../postman/collections/My API: 45288920-e06bf878-2400-4d76-b187-d3a9c99d6899
  environments:
    ../postman/environments/dev.postman_environment.json: 45288920-abc12345-...

Collection v3 Folder Format

Each collection is a directory (not a single JSON file). It contains:

• .resources/definition.yaml — collection metadata
• *.request.yaml — individual request files
• Subdirectories for folders within the collection

Request files contain:

$kind: http-request
url: https://api.example.com/users
method: GET
order: 1000

---

Postman CLI vs Newman

The Postman CLI is the official replacement for Newman:

Feature	Postman CLI	Newman
Maintenance	Official Postman support	Community-driven
Security	Digitally signed binary	Open-source
Governance	Enterprise API governance	Not available
Auth	Postman API key	No authentication
Spec linting	Built-in	Not available
HTTP requests	postman request command	Not available

Always use postman-cli, never Newman.