# Postman CLI

> Postman CLI reference and git sync file structure knowledge - provides context for CLI-based commands (send-request, generate-spec, run-collection, context)

- Skill: `postman-devrel/postman-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add postman-devrel/postman-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/postman-devrel/postman-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: postman-devrel (https://skillmd.com/u/postman-devrel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/postman-devrel/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

```bash
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:

```yaml
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:
```yaml
$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.