pp-postman-explore

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/developer-tools/postman-explore/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Postman Explore — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `postman-explore-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install postman-explore --cli-only
   ```
2. Verify: `postman-explore-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Pick this CLI when you need to programmatically discover, compare, or watch community-contributed Postman Collections / workspaces / APIs / flows. Ideal for AI agents asked to find a canonical Postman Collection for a vendor, for API curators comparing publishers in a category, and for monitoring scripts that watch network changes. Skip this CLI for managing your own private Postman workspace — that's the authenticated Postman product API, which is a different surface entirely.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Discovery that compounds locally
- **`canonical`** — One command finds the best community Postman Collection for a vendor, ranked by publisher verification, fork count, and recency.

  _When the user asks an agent for a vendor's Postman Collection, this returns the best canonical choice in one call instead of forcing the agent to dedupe a search result list._

  ```bash
  postman-explore-pp-cli canonical stripe --json
  ```
- **`top`** — Rank entities by any metric (weekForks, monthViewCount, etc.) with category and entity-type narrowing.

  _When agents need to recommend the most-forked collections THIS week, not the all-time leaders, this is the only path that works._

  ```bash
  postman-explore-pp-cli top --metric weekForkCount --type collection --category payments --limit 10
  ```
- **`similar`** — Given an entity numeric id, return collections with overlapping name, summary, and category — ranked by FTS relevance score against the seed entity's text.

  _When an integrator finds one collection but wants to compare against alternatives, this returns the rivals in one call rather than forcing a fresh search._

  ```bash
  postman-explore-pp-cli similar 10289 --limit 5 --json
  ```

### Comparative analysis
- **`publishers top`** — Aggregate fork counts across every entity per publisher within a category; rank teams by total community gravity.

  _API curators picking between vendors need cross-publisher comparison. Agents recommending an integration partner need this to break ties._

  ```bash
  postman-explore-pp-cli publishers top --category developer-productivity --limit 5 --json
  ```
- **`category landscape`** — For a category slug, return: total entity counts per type, top 5 publishers by aggregate fork count, and top 5 entities by viewCount. One command, one structured payload.

  _API curators evaluating a vertical (payments, AI, devops) want one snapshot of who dominates and what's popular; this is exactly that snapshot._

  ```bash
  postman-explore-pp-cli category landscape payments --json
  ```

### Time-windowed signals
<!-- PATCH: describe current drift implementation accurately as updated-within-window, not snapshot diff. -->
- **`drift`** — Report locally synced entities whose API-side `updatedAt` timestamp falls inside a time window.

  _Agents tracking recently updated vendor collections rely on this after a periodic `sync`; it is an updated-within-window view, not a two-snapshot removed-entity diff._

  ```bash
  postman-explore-pp-cli drift --since 7d --type collection --json
  ```
- **`velocity`** — Rank collections by acceleration ratio: (weekForkCount × 4) / monthForkCount. Surfaces collections breaking out before they top the popular list.

  _Catching a breakout collection before it tops the popular sort is high-value for API curators tracking emerging vendors._

  ```bash
  postman-explore-pp-cli velocity --type collection --top 10
  ```

### Quality signals
- **`browse`** — When passed --verified-only, the browse command filters to entities owned by publishers with the verified-team flag set.

  _When you want only the official-vendor collections (not community forks), this is the cleanest filter._

  ```bash
  postman-explore-pp-cli browse collection --verified-only --category payments --json --limit 5
  ```

## HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

## Discovery Signals

This CLI was generated with browser-observed traffic context.
- Capture coverage: 17 API entries from 24 total network entries
- Protocols: rest_json (60% confidence), rpc_envelope (95% confidence)
- Auth signals: none
- Generation hints: client_pattern:proxy-envelope, uses_browser_http_transport, no_auth_required, skip_clearance_cookie
- Emitted command surface: browse; networkentity get-network-entity; networkentity get-network-entity-counts; category list-categories; category get; team get-workspaces; team get; search-all

## Command Reference

**category** — Manage category

- `postman-explore-pp-cli category get` — Returns full details for a category by its URL slug (e.g., `artificial-intelligence`, `developer-productivity`,...
- `postman-explore-pp-cli category list-categories` — Returns all categories used to organize the API network (e.g., AI, E-commerce, Communication, DevOps). Categories...

**networkentity** — Manage networkentity

- `postman-explore-pp-cli networkentity get-network-entity` — Returns full entity record by internal numeric id (the `id` field from `listNetworkEntities`, NOT the `entityId` UUID).
- `postman-explore-pp-cli networkentity get-network-entity-counts` — Returns aggregate counts across the entire public API network: collections, workspaces, APIs, flows, notebooks,...
- `postman-explore-pp-cli networkentity list-network-entities` — List public collections, workspaces, APIs, or flows. Supports category filtering, pagination, and minimum-fork...

**search-all** — Manage search all

- `postman-explore-pp-cli search-all` — Search collections, workspaces, requests, flows, and teams by free-text query. With no `queryIndices` set, the...

**team** — Publisher teams on the API network

- `postman-explore-pp-cli team get` — Returns small profile object (id, name, description, publicHandle, profileURL, createdAt, updatedAt) for a team by...
- `postman-explore-pp-cli team get-workspaces` — Returns the array of public workspaces owned by a team identified by its `publicHandle` (e.g., `stripedev`,...


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
postman-explore-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code