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